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This is the second book in a series of three on the Atari ST. 
The first concerned the VDI (the Virtual Device Interface). 
COMPUTERS Technical Reference Guide— Atari ST, Volume Two: 
The GEM AES takes you further into the underpinnings of the 
ST's fast, friendly GEM interface with a thorough examination 
of the Application Environment Services (AES). 

This book will help you to understand the AES. Using the 
AES will enable you to make your ST programs as friendly 
and cooperative with the user as the intuitive GEM environ- 
ment can make them. 

COMPUTEl's Technical Reference Guide— Atari ST, Volume 
Two: The GEM AES explains ST multitasking, window opera- 
tion, dialog boxes, alert boxes, menus, input, and output. The 
latter half of this book is a complete reference to AES func- 
tions listed according to opcode, along with an alphabetical in- 
dex. These functions are complete with C bindings, an 
explanation of input and results, and more. 

In each chapter, functions are covered individually in de- 
tail with examples of their use, culminating in fully com- 
mented sample programs written in C, machine language, and 
BASIC. 

If you are an ST programmer, this is the reference you 
have been looking for. 
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Chapter 1 

GEM and the AES 







Although many people think of GEM as a computer 
operating system, Digital Research, Inc. (DRI), the creators of 
GEM, prefer to call it an operating environment. Traditional 
microcomputer operating systems provide access to the most 
basic I/O (Input/Output) devices, like the keyboard, display 
screen, and disk drives, but they only support the transfer of 
text characters. Newer microcomputers, however, offer a more 
sophisticated class of input/output operations, which are com- 
monly grouped together under the term graphics interface. 
Computers that offer such an interface allow users to operate 
programs by manipulating graphics objects on the display 
screen with a pointing device known as a mouse, rather than 
requiring them to type in carefully worded commands. 

GEM (an acronym for Graphics Environment Manager) 
was designed to provide this graphics interface. An additional 
level of system routines, it sits on top of the low-level 
input/output functions furnished by the computer's own op- 
erating system. Because GEM supplements, rather than re- 
places, the existing operating system, it's possible to write 
"old-style" computer programs on the ST that take text input 
from the keyboard, without using GEM at all. These are called 
TOS (Tramiel Operating System) programs. TOS programs 
don't take full advantage of the capabilities of the ST. 

GEM programs are easier to operate, because of their vi- 
sual orientation — as the old saying goes: One picture is worth 
a thousand words. Anyone who's ever taken out the garbage 
should be able to understand the effect of dragging a file on 
the Desktop. Moreover, GEM provides a consistent context for 
program operation. Users of GEM programs who want to 
learn what the various program options are, know that they 
can always find the menu selection on the menu bar at the top 
of the screen. Other standard features like dialog boxes, alert 
boxes, icons, and file selectors provide a comfortable frame of 
reference even when you're using programs you've never seen 
before. 
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From the programmer's standpoint, GEM makes it easy to 
provide the user with such advanced features as overlapping 
windows, drop-down menus, and icons. These features would 
be difficult for programmers to implement without the GEM 
environment. GEM also offers portability for programs among 
the various versions of the ST and also limited portablility to 
the IBM PC and compatibles. GEM also includes facilities to 
provide output without regard to the device-specific resolu- 
tion. This is of particular interest now that Atari has an- 
nounced plans to introduce a laser printer. 

The programmer should keep in mind, however, that 
portability has its price. A more generalized program will al- 
ways be slower and less efficient than a more specific one. Al- 
though the ST has a fast and powerful processor, its operations 
will slow down if GEM has to do a lot of internal coordinate 
conversion and range checking. Programmers may find that in 
some cases they must use more device-specific methods to 
achieve the desired level of performance. While portability is 
nice, you'll have to decide what performance compromises are 
acceptable in order to gain its benefits. 

GEM Organization 

Though GEM is spoken of as a single entity, it's actually made 
up of a number of parts. The two major divisions are the Vir- 
tual Device Interface (VDI) and the Application Environment 
Services (AES). 

The VDI was discussed in Volume One of this series. It 
provides a number of low-level, device-independent drawing 
routines, also known as graphics primitives. It also supplies 
some fundamental input functions for receiving data from the 
mouse and keyboard. 

The AES provides user-interface features called environ- 
ment services. These are the features usually associated with 
GEM: drop-down menus, overlapping windows, icons, and di- 
alog boxes. 

It's important to understand that ST system software is hi- 
erarchical (see Figure 1-1). At the bottom of the hierarchy are 
the routines known as the BIOS (Basic Input/Output System), 
XBIOS (extended BIOS) and Line A (graphics) routines. These 
routines communicate directly with the ST hardware and 
peripherals. The GEMDOS (Disk Operating System) builds on 
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the disk-access routines in the XBIOS to provide a filing sys- 
tem. Similarly, the GEM VDI builds upon low-level Line A 
graphics routines to provide higher-level, device-independent 
graphics routines. Finally, the GEM AES uses the graphics and 
input primitives supplied by the VDI to provide a sophisti- 
cated user interface. 

Figure 1-1. Parts of the ST Operating System 


AES 

6EHP0S; VDI 
BIOS | XBIOS 
Line 'A* Routines 


GEM 

TOS 


The AES is itself made up of a number of parts. At the 
lowest level is the multitasking kernel. Its job is to provide 
GEM with a limited form of multitasking. Multitasking allows 
processing time to be divided between the primary applica- 
tion, the desk accessory programs, and the AES Screen Man- 
ager (discussed below), so that they all appear to be running 
at the same time. Of course, the ST's 68000 microprocessor 
can't execute instructions for more than one task at a time, but 
because it operates at a high rate of speed, it's possible to 
switch between tasks quickly enough to give the user the im- 
pression that they're running simultaneously. 

The scheduling system for tasks is fairly simple. The ker- 
nel maintains two lists of tasks, the Ready list, and the Not- 
Ready list. In order to understand the difference between the 
two, you must first know something about GEM events. In 
single-tasking microcomputer systems, a program finds out 
about an I/O event — such as the user pressing a key on the 
keyboard — by continuously checking the status of the I/O de- 
vice until a specified event occurs. The processor is on hold, 
waiting until it receives input. 

Multitasking systems use a more efficient process. They 
suspend a task that's waiting for some I/O event by placing it 
on the Not-Ready list. Then the other tasks take turns running 
until the event occurs. 

GEM provides a number of system calls for just this pur- 
pose. These calls are part of the Event Library, and they allow 
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an application to wait for a keypress, mouse button press, 
mouse movement, timer alarm, and/or a message from an- 
other task. Tasks that use these calls to indicate they're wait- 
ing for an I/O event are put on the Not-Ready list. They're 
inactive until the event they are waiting for occurs. All the 
tasks that are ready to run are kept on the Ready list, where 
they take turns executing. 

The task currently running is at the top of the Ready list. 
When that task makes a call to one of the AES library 
routines, the Dispatcher portion of the kernel takes control as 
soon as the call is completed. If the call was an event call, in- 
dicating that this task wants to wait for an I/O event, the Dis- 
patcher moves the task from the Ready list to the Not-Ready 
list. Otherwise, it merely terminates execution of the task, 
moves it from the top of the Ready list to the bottom, and 
moves all of the rest of the tasks up one place on the list. 
Control is handed over to the new task at the head of the list, 
and it's allowed to run until it makes an AES call. 

Unlike some multitasking systems, where each task gets a 
fixed amount of time to execute, the AES dispatcher will not 
preempt a running task. The only way it can get control is for 
the task to make an AES call. Therefore, if your application 
goes for a long time without making an AES call (during ex- 
tensive math calculations, for example), multitasking will 
break down. The Screen Manager task will not run, and the 
GEM features that it handles — such as the menu bar — will no 
longer work, puzzling the user. Therefore, it's recommended 
that your program make periodic AES calls, if only to keep the 
dispatcher working. One "harmless" AES call that you can 
make is to evnt_timer( ), specifying that your application 
wishes to wait for a period of zero milliseconds. 

While tasks rotate through the Ready list in a fixed order, 
tasks on the Not-Ready list aren't arranged in any particular 
sequence. When an awaited I/O event occurs, the task waiting 
for that event is removed from the Not-Ready list and added 
to the bottom of the Ready list. 

Another vital part of the AES is the Screen Manager. The 
Screen Manager is a separate GEM task that shares processor 
time with the main application program. 

To understand its function, you must first realize that 
many of the user-interface features of GEM require coopera- 
tion between GEM and the application program in order to 
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work. Although most GEM applications share common user- 
interface features, such as menus and dialog boxes, these fea- 
tures prompt a unique response from each application. GEM 
therefore provides for a division of labor between the AES and 
the application. Since only the application knows what it 
wants to display, it alone is held responsible for everything 
that goes on in the active (topmost) window. 

The Screen Manager's job is to monitor mouse move- 
ments outside of the active window, provide visual feedback 
where appropriate, and report the outcome of the user's activ- 
ity when that activity has some meaning to the application. 

For example, say the user moves the mouse to the size 
box at the bottom right comer of a window border. When the 
mouse pointer moves out of the active area of the window and 
into the window border, the Screen Manager watches it. If the 
user presses the left mouse button while the pointer is over 
the size box and holds it down while moving the mouse, the 
Screen Manager is responsible for drawing a dotted window 
outline that follows the mouse pointer. When the user releases 
the mouse button, the Screen Manager sends a message to the 
application telling it the size of the window requested, and 
control returns to the application. Then it's up to the program 
to decide whether to change the size of the window in compli- 
ance with the user's request. 

The Screen Manager's major areas of responsibility are 
handling the drop-down menu system and the window con- 
trols. When the mouse pointer crosses into the menu bar, the 
Screen Manager saves the screen rectangle where a menu is to 
be displayed, and then it displays the menu. It handles the 
highlighting of menu items as the pointer travels over them, 
and redisplays the saved screen area if the left mouse button 
is clicked. If the button was clicked while the pointer was over 
a menu item, the Screen Manager sends a message to the 
application, specifying the menu and item numbers selected. 
Similarly, when the user clicks on one of the window controls, 
such as the closer (close box), the fuller (full box), the sizer 
(size box), scroll bars, or arrows, the Screen Manager sends 
the appropriate message to the application. If the user drags 
the window's drag bar, the Screen Manager may be able to re- 
draw the window in the new position itself, so long as the vis- 
ible portion of the window remains the same. The Screen 
Manager will also notify the application if the user clicks in an 
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inactive window, signaling that he or she wishes to make it 
the active one. 

While the multitasking kernel and the Screen Manager are 
necessary to the functioning of GEM applications, they do 
their work “behind the scenes." The programmer doesn't com- 
municate directly with them. 

The portion of the AES that's most accessible to the pro- 
grammer, and therefore the part dealt with here in greatest de- 
tail, is known as the AES Libraries. These are collections of 
operating system calls that perform tasks related to the setup 
and operation of the user interface. There are eleven different 
libraries in all. Their names and functions are as follows: 

Application Library. This library contains routines to reg- 
ister an application with GEM, and to send messages back and 
forth between tasks. 

Event Library. The functions found here allow you to put 
the application on the Not-Ready list until certain I/O events 
occur (mouse button press, mouse movement, keypress, timer 
expiration, or message events) and to pass information about 
the events back to the application, once they do occur. 

Menu Library. The routines in this library allow the 
application to establish and maintain drop-down menus. 

Object Library. This library contains routines that allow 
the program to interact with various types of GEM objects. 
GEM objects are data structures that form the basic building 
blocks of icons, menus, dialog boxes, and alert boxes. 

Form Library. This library contains routines that allow 
the application to display and handle dialog and alert boxes. 

Graphics Library. The routines in this library perform 
some graphics functions (mainly related to managing box out- 
lines as they appear on the Desktop), and some low-level I/O 
functions. 

Scrap Library. The functions in this library are used to 
read and write data to clipboard files on disk. Clipboard files 
store data for interchange among applications. 

File Selector Library. This library contains a single rou- 
tine that displays and manages the standard file-selection 
dialog. 

Window Library. This library contains routines that sup- 
port the creation and management of overlapping windows. 

Resource Library. The functions in this library enable the 
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application to load and use the object information stored in re- 
source (.RSC) files. This information is used to display menus, 
dialog boxes, and so on. 

Shell Library. The routines found here deal with loading 
and running programs. The Shell Library allows you to load 
and run other applications from within an application (like the 
Desktop does). 

At this point, you may be wondering where the GEM 
Desktop fits into the scheme of things. Strange as it seems, the 
Desktop is not really an integral part of the GEM AES. Rather, 
it is itself an application program, and as such, it uses GEM 
the same way your application programs will. Of course, you 
should bear in mind that most, if not all, of the AES Library 
functions were originally written to facilitate creation of the 
Desktop application. Although most of these library calls are 
general enough to be of use in almost any application, a few 
are of interest mainly for their use in the Desktop. 

Allocating RAM 

The parts of the AES discussed so far consist of program code 
located in the ST's operating system ROM. The AES also uses 
some free system RAM. 

The first RAM area it must allocate is the Menu/ Alert 
Buffer. As was mentioned above, when the user pulls down a 
menu, the Screen Manager automatically saves the portion of 
the screen that lies under the menu. The Menu/Alert Buffer is 
the place where this screen information is stored. This buffer 
has to be large enough to accommodate a quarter of the screen 
at any one time. Since the ST uses 32K of screen memory in 
all of its resolution modes, the Menu/ Alert Buffer must oc- 
cupy 8K of RAM. 

AES may also need some RAM to load resource files. Re- 
source files are data files which define GEM object trees, the 
data structures used to create menus, dialog boxes, and icons. 
The amount of RAM required depends on the size of the re- 
source files to be loaded. 

Finally, GEM may also need to use some free RAM for 
the Desk Accessory Buffer. This is the area used to store up to 
six desk accessory programs at boot time. Desk accessories are 
separate special programs. They can be found on the root di- 
rectory of the startup disk. Their file names end in ".ACC”. 
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These programs may be run from the "Desk" menu of another 
application. 


Using the AES Libraries 

You may think of the AES Libraries as a collection of subrou- 
tines that you can call from your program. In order to pass 
data to these subroutines and receive data from them in re- 
turn, you must allocate storage space in computer memory for 
a number of data arrays. The AES uses information from six 
different arrays, each of which is made up of a number of 16 - 
bit (two-byte) values. These arrays are as follows: 


Array Name 

global 

control 

int_in 

int_out 

addr_in 

addr_out 


Size 

15 words 
5 words 

16 words 
7 words 

2 long words 
1 long word 


Function 
Global parameters 
Control parameters 
Input parameter 
Output parameters 
Input addresses 
Output addresses 


The array named global contains certain information 
about GEM and the application which must be available to all 
of the library routines. The array contains nine elements, the 
first three of which consist of two-byte words. The rest are 
four-byte long words. These elements are as follows: 


Address 

global 

Element 

global(0) 

Name 

ap_version 

global +2 

global(l) 

ap_count 

global +4 

global(2) 

ap_ id 

global +6 

global(3,4) 

ap_private 

global +10 

global(5,6) 

ap_ptree 

global +14 
global +18 
global +22 
global +26 

global(7,8) 

global(9,10) 

global(ll,12) 

global(13,14) 

ap_lresv 
ap_ 2resv 
ap_3resv 
ap_4 resv 


Contents 

The GEM AES version 
number 

The maximum number of 
concurrent applications sup- 
ported by this GEM version 
A unique ID number for the 
currently active application 
(used to pass messages to it) 
A private storage place to be 
used by the application 
A pointer to the address of 
the header of the object tree 
loaded with rsrc_load( ) 
Reserved for future use (0) 
Reserved for future use (0) 
Reserved for future use (0) 
Reserved for future use (0) 
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As you can see, there are official GEM names for each of 
these elements. The first, ap_ version, is an internal GEM AES 
version number, supplied by GEM after an application is ini- 
tialized with the appl_init( ) call. The version in use at the 
time of this writing was 288. The second, ap_count, is also re- 
turned by GEM, and it shows how many applications can run 
concurrently under this version of GEM. Since the current ST 
does not support full multitasking, only one main application 
can run at a time. The third element, ap_id, is where GEM 
stores the unique application ID number that identifies this 
application. The ID number can be used when passing mes- 
sages to this application from another task (such as a desk ac- 
cessory). This ID number is the same number that is supposed 
to be returned by the appl_init( ) call, but some versions of 
the C language bindings don't correctly return the ID number. 
Since appl_init( ) does place the ID number in the global ar- 
ray, an application can find it out by reading that array di- 
rectly. The C library assigns the name gl_apid to the ap_id 
element, so a C application can find out its value by declaring 
gl_apid as an external int and using the contents of that 
variable. 

The rest of the global array is made up of 32-bit long 
words. The ap_private element is reserved for use by the 
application, any four bytes of data, as determined by the pro- 
grammer, may be stored here. The ap_ptree element is where 
the AES stores a pointer to the header of the object tree 
loaded with the rsrc_Joad( ) call. The other four elements are 
reserved for future use. 

The second data array used by the AES is named control, 
and it consists of five elements, each two bytes in length. The 
information stored in each of these elements is as follows: 


Address 

Element 

control 

control(O) 

control +2 

control(l) 

control +4 

control(2) 

control +6 

control(3) 

control +8 

control(4) 


Control Parameter 
Command opcode (operation code) 
Number of integer inputs passed in int_in 
Number of integer results returned in 
int_out 

Number of input addresses passed in 
addr_in 

Number of addresses returned in addr_out 


The first element of the control array is used to pass the 
opcode. Since all of the AES routines have a common entry 
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point, there has to be some way to tell the AES which com- 
mand is to be executed. Therefore, each command is given an 
identification number called an opcode. These opcodes are 
grouped by library. The Application Library uses opcodes 
10-19, the Event Library uses opcodes 20-26, and so on. 

The remaining four elements are used to indicate how an 
AES call utilizes the parameter arrays int_in, int_out, addr_in, 
and addr_out. The two input parameter arrays, int_in and 
addr_in, are used by the application to pass values to the AES 
library calls. These arrays give the function call information 
about how the application wants the calls to operate. The two 
output parameter arrays, int_out and addr_out, are used by 
the AES library to return results to the application. The last 
four control array elements are used to indicate how many pa- 
rameters are being passed in each direction. The application 
uses control(l) to specify the number of input integers being 
passed in the int_in array and control(3) to indicate the num- 
ber of addresses being passed in addr_in. The AES uses con- 
trol^) to specify the number of integers being returned in 
int_out and control(4) to specify the number of addresses it 
has returned in addr_out. 


□ 

n 

□ 
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Machine Language AES Calls 

If you are programming at the machine-language level, you 
must explicitly reserve memory space for each of these arrays 
and put the proper values in each of the memory locations 
before calling the command. The first step is reserving space 
for each of the data arrays: 

Array Name Storage Space 
global: .ds.w 15 

control: .ds.w 5 

int_in: .ds.w 16 

addr_in .ds.l 2 

int_out: .ds.w 7 

addr_out: .ds.l 1 

Since each AES call uses a fixed number of inputs and 
outputs, it's possible to determine the maximum number of 
bytes need for these arrays. In addition to allocating data-array 
space, you must also define an AES parameter block. This pa- 
rameter block contains the beginning address of each of the 
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six data arrays: 

apb: .dc.l control,global,int_in,int_ out,addr_in,addr_out 


These addresses must be arranged in the order shown 
above, since the AES uses the parameter block to find the data 
arrays. Once you've set up the arrays and the parameter block, 
you must place any input parameters into their correct place in 
the data arrays. For example, to execute the graf_mouse( ) 
command to change the shape of the mouse pointer, you 
would transfer the following values: 


move #78,control 
move #l,control+2 
move #l,control+4 
move #l,control+6 
move #0,control+8 
move #3,int_in 


;Move the graf— mouse opcode (78) to 
control(0) 

;Move the length of int—in array (1) to 
control(l) 

;Move the length of int_out array (1) to 
control(2) 

;Move the length of addr_in array (1) to 
control(3) 

;Move the length of addr_out array (0) to 
control(4) 

;Move the mouse pointer shape code to 
int_ in(0) 


Now you're ready to call the AES. First, place the address 
of the AES parameter block into register dl. Next, move the 
AES identifier code (200 or $C8) into register dO. Finally, call 
the AES with a "trap 2" instruction. This initiates a software- 
generated exception (similar to a hardware interrupt) that 
causes execution of an exception-handler routine. In this case, 
the routine executed is the one whose address is pointed to by 
the long word beginning at location 136 ($88). This routine is 
the one used to handle all GEM VDI and AES calls (VDI calls 
are identified by placing a value of 115 or $73 into register 
dO). The instruction sequence used for making a AES call 
looks like this: 


move.l #apb,dl ;Move address of AES parameter block to dl 
move.l #$C8,dO ;Move AES identifier ($C8) into dO 
trap #2 ;call GEM entry point 

Please note that the procedures outlined above just cover 
the steps required to make the AES call itself. Before you get 
to that stage, you must take preparatory steps to set up the 
program environment (for instance, allocating stack space) and 
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n 
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the graphics environment (opening a GEM output workstation). 
This will be outlined in the next chapter and illustrated in an 
example program. 

ST BASIC VDI Calls 

Making ST BASIC calls employs the same fundamental strat- 
egy for AES calls as making calls from machine language pro- 
grams. The only difference is that BASIC does much of the 
preparatory work for you. Since the BASIC interpreter itself 
must use AES calls, it already has set aside memory for the 
data arrays control, global, int_in, int_out, addr__in, and 
addr_out, and has set up a parameter block with the starting 
address of each of these arrays. BASIC assigns the reserved 
variable GB (for GEM Base) to the address of the AES Param- 
eter Block. This means that the starting address of the control 
array can be found by using the PEEK command to obtain the 
address stored at the four bytes starting with address GB. In 
order to PEEK a four-byte number in ST BASIC, you must 
specify the address to PEEK as a double-precision number. 

This can be done by assigning the value in GB to a variable 
that has been declared to be double-precision: 

10 apb# = gb 
20 control = PEEK(apb#) 

The pound sign at the end of apb# tells BASIC that apb# 
is a double-precision variable. Since each address found in the 
Parameter Block is four bytes long, you can find the address of 
each succeeding data array by PEEKing the next four bytes in 
memory: 

30 global - PEEKIapb# + 4) 

40 gintin = PEEKIapb# +8) 

50 gintout = PEEKIapb# +12) 

60 addrin# - PEEKIapb# + 16) 

70 addrout# = PEEKIapb# + 20) 

Notice that we used the variable names gintin and gintout 
for the int_in and int_out arrays. That's because the original 
version of ST BASIC doesn't allow the underscore character in 
variable names, and the names intin and intout are already re- 
served for the data arrays used by the GEM VDI. Notice also 
that we've placed a pound sign at the end of the variables that 
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hold the addresses of addr_Jn and addr_out. That's because 
the values in these arrays are four bytes long. By declaring the 
type of these variables as double-precision, BASIC will know 
it should PEEK or POKE four bytes at a time. 

You may read the contents of the various data arrays, or 
write to them, by using the PEEK and POKE commands. Since 
each element in gintin and gintout is two bytes long, you must 
multiply the element number by 2 to get the proper offset for 
the POKE statement. Each element in addrin# and addrout# is 
four bytes long, so you must multiply the element number by 
4 to get the proper offset for those arrays. To write a value to 
int_out(l), you'd POKE gintout +4, and to write a value to 
addr_in(3), POKE addrin +12. The following short program 
shows how to change the shape of the mouse pointer from an 
arrow to a pointing hand with the graf_mouse( ) call from 
BASIC. 

10 apb# = gb 
20 control = PEEK(apb#) 

30 global = PEEK(apb# + 4) 

40 gintin = PEEK(apb# +8) 

50 gintout = PEEKtapb# +12) 

60 addrin = PEEKtapb# + 16) 

70 addrout — PEEKtapb# + 20) 

80 POKE gintin,3: REM Pointing hand is shape number 3 
90 GEMSYS(78) : REM call gra£_mouse( ) 

This method of making an AES call from BASIC is similar 
to that used in the machine language program shown above, 
in that the input parameters are placed directly in the int_in 
array. But you'll also notice that the GEMSYS call takes care 
of a lot of the detail work. First, there was no need to POKE a 
value for the opcode into control(O), because the opcode is 
passed as part of the GEMSYS call. Second, the GEMSYS 
command performs the same tasks as the three lines of ma- 
chine language code: It places the address of the parameter 
block into register dl, places the AES identifier code into dO, 
and then executes the TRAP #2 statement. 

The original version of ST BASIC doesn't contain any 
built-in commands that perform the same functions as AES 
calls. Although not yet released at the time of this writing, the 
revised MCC BASIC promises to include a few, such as ASK 


U 


15 




MOUSE, which returns the current mouse position like 
graf_mkstate( ). And the revised BASIC is slated to include re- 
served variables for the data arrays, such as GEM— ADDRIN, 
GEM-ADDROUT, GEM_CONTRL, GEM_GLOBAL, 
GEM-INTIN, GEM-INTOUT, and a STATUS variable to re- 
turn information from AES calls. Even so, BASIC programmers 
will still have to learn the details of making AES calls if they 
want to take full advantage of GEM. 

Calling the AES Routines from C 

It's much easier to make AES function calls from C than from 
either machine language or BASIC. That's because C compiler 
packages for the ST include one or more function libraries 
known as GEM bindings. These bindings are object-code li- 
brary files that define a separate named function for each 
GEM call. When the C program is linked to the proper library 
files, it can call GEM functions as if they were part of the C 
language. 

These library fries also allocate storage space for the data 
arrays. But the programmer is not responsible for placing data 
directly into these arrays. Instead, input parameters are passed 
to the binding functions as part of the function call. For example, 
you could execute the graf_mouse( ) command performed by 
the BASIC and machine language programs like this: 

int dummy, shape = 3; 

gra£_mouse(shape,&dummy); 

The function defined as graf— mouse( ) in the library takes 
the parameter shape that's passed to it, puts it in int— in(0), and 
puts the address of the parameter dummy in addr_ in(0). It also 
puts a 1 in control(l), control(2), and control(3), a 0 in con- 
trol^), and places the command opcode (78) in control(O). The 
function graf— mouse then loads registers dO and dl with the 
proper values and executes a TRAP #2 instruction. In short, it 
takes over all of the repetitive steps associated with making 
GEM calls, allowing the programmer to concentrate on the es- 
sential aspects of the function. 

Making GEM calls from C is easy. It's because of this, and 
because C programs are relatively small and quick (compared 
to other high-level languages), C has become the language of 



16 





choice for software development on the ST. Most of the exam- 
ples in this book are written in C. On occasion, however, ma- 
chine language and BASIC examples will be included as well, 
to show how the C examples could be translated. The C func- 
tion names will be used as they appear in the official Digital 
Research GEM bindings, since they have been adopted by the 
manufacturers of most other C compilers as well. Refer to the 
user's manual of your particular C compiler for specific infor- 
mation concerning the C function names. 

The C programs in this book are designed to work specifi- 
cally with the Alcyon C compiler, the one officially supported 
by Atari, and with Megamax C, which also provides a very 
complete development environment. For these compilers, the 
integer data type tint) refers to a 16-bit word of data. Other 
compilers, such as Lattice C, use a 32-bit integer as the default 
data type. When compiling the programs in this book with 
such compilers, you should substitute the word short for each 
reference to int. For the sake of simplicity, we have not used 
the portability macros such as WORD, which use the C pre- 
processor to define a 16-bit data type that will be valid for any 
compiler, but you are free to do so. 
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Chapter 2 


Starting an 
Application: 
Windows, Part 1 




The first step 


in starting a GEM application is to 
initialize it with a call to the AES Application Library routine 
appl—init( ). This call registers the application with the AES, 
which then initializes several items in the global data array. 
One of these is an application ID number which the AES as- 
signs to the application. This ID number is used by other tasks 
(the GEM Screen Manager, for instance) when they wish to 
communicate with the application through its message buffer. 
The C format for the call is 


int ap_id; 

ap_id = appl_init( ); 

where ap—id is supposed to be the application ID number. 
Note, however, that as of this writing, the bindings for all C 
compilers which derive from source code supplied by Atari 
(such as Alcyon and Megamax C), do not correctly return the 
application ID number. Instead, these bindings always return a 
value of 1 in the variable ap_id. The actual ID number is, 
however, correctly stored in the third element of the global ar- 
ray. This element is assigned the variable name gl_apid by the 
bindings. If your C compiler library does not return the correct 
value, you can work around this bug by declaring the external 
variable gl—apid and getting the value from this variable: 

extern int gl—apid; 
int ap_id; 
appl_int( ); 
ap_id = gl_apid; 

If you've registered an application with the AES, be sure 
to "unregister" it before your application terminates. You per- 
form this function with a call to appl—exit( ); as follows: 

int status; 

status = appL_exit(); 


21 



CHAPTER 2 


Status is an error return code. A value of 0 in status indi- 
cates that an error occurred, while a positive integer value in- 
dicates that the application exited successfully. 

Opening a Virtual Screen Workstation 

Since most GEM programs use at least some of the VDI 
graphics function, you'll need to prepare a graphics output 
environment by opening a VDI screen workstation. Though 
this process is covered in detail in Volume One of this series, a 
brief review follows. The VDI call used to open a graphics 
workstation is V—opnvwk( );. It's invoked like this: 

int input[12]; 
int output[57] 
int handle; 

v_opnvwk(input, &handle, output) 

The input array consists of 12 words of data passed to the 
VDI to specify the initial default graphics settings for the 
workstation. With two exceptions, you can set these to a de- 
fault value of 1. The first of these exceptions is input[10], 
which is used to select the graphics coordinate system. Initial- 
ize this value to 2, indicating that you wish to use raster co- 
ordinates, which correspond to the ST's actual screen 
dimensions. The second exception is input[0], the device ID 
number. On ST systems that have the GDOS extensions 
loaded, this device number specifies the screen resolution 
mode. To find the resolution mode, use XBIOS command 4. C 
programmers can use getrez, a macro defined in the file 
osbinds.h to call this function. Getrez returns the numbers 0 
for lo res, 1 for medium res, and 2 for high res. To get the 
proper screen device number, you must add 2 to the value re- 
turned by getrez: 

#include <osbinds.h> 
int rez, work_in[12]; 

rez = getrezf ) 
work_in[0]= rez + 2; 
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Machine language programmers can perform the getrez 
call using the following code: 

move.w #4,-(sp) * push command number on stack 

trap #14 * call XBIOS 

addq.l #2,sp * pop command number off the stack 

The resolution will be returned in register dO. 

The other input value is &handle. This is a pointer to the 
variable that holds the physical workstation ID number of the 
screen device. In order to discover this workstation handle, the 
AES Graphics Library function, graf—handle( ) must be used. 
The format for this call is 

int phys_ handle, cellw, cellh, chboxw, chboxh; 

phys_ handle = graf_handle(&cellw, &cellh, &boxw, &boxh); 

The physical screen handle is returned in phys— handle. 
Before making the v_opnvwk call, phys_handle should be 
stored in the variable handle. In addition to the the physical 
screen handle, graf_handle( ) returns some interesting infor- 
mation about the size of the default-system text font used in 
menus and dialog boxes. The width and height of the charac- 
ter cell are returned in cellw and cellh. The character cell is the 
entire space taken up by each character, including the inter- 
character spacing. The width and height of a box that sur- 
rounds the text cell are returned in chboxw and chboxh. The 
chboxw and chboxh measurements are significant because 
many GEM Objects are scaled to these sizes. For example, the 
window controls such as the title bar, close box, size box, and 
scroll bars are chboxw wide and chboxh tall. 

Opening a Window 

The next step in setting up an application is to open an output 
window. Windows are an integral part of the GEM user inter- 
face. They are used to divide a single display screen into sepa- 
rate, sometimes overlapping, sections, each surrounded by a 
visible border. This makes it possible for a single application 
to present several distinct types of information on the same 
screen. For example, a program could display help information 
in one window and data in another. Windows also facilitate 
sharing the display between the application and one or more 
desk accessories. 
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There are two types of GEM windows, the Desktop window 
and application windows. The Desktop window is controlled 
by the GEM AES, and is present when any GEM application 
(such as the Desktop program) is running. It covers the entire 
display area and is divided into two parts, the menu bar and 
the Desktop work area. The menu bar stretches across the top 
line of the screen and is the same height as a character cell in 
the default text font. When a GEM application first starts, the 
menu bar contains the name of the application file. The appli- 
cation may request the AES to replace this filename with a 
drop-down menu, as will be seen in a later chapter. The Desk- 
top work area covers the rest of the display space. It provides 
a background for windows which the application opens. The 
default background appears as a field of light green on a color 
system and gray on a monochrome system. 

Application windows are opened and controlled by the 
application. In addition to a border, these windows may con- 
tain a number of different components, located in and around 
the window borders (see Figure 2-1). Most of these allow the 
user to control certain aspects of the window's appearance and 
function. These control features include a title bar, a move bar, 
an information line, a close box, a full box, and horizontal 
and/or vertical slide bars. 


Figure 2-1. The Component Parts of a GEM Window 
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Title bar. The title bar stretches across the top of the win- 
dow and is used to display the name of the window. 

Move bar. The move bar occupies the same area as the ti- 
tle bar and has no visible characteristics to distinguish it from 
the title bar. The move bar allows the user to move the win- 
dow around on the screen. 

Information line. This line also stretches across the top of 
the window, directly below the title bar. It is used by the pro- 
gram to display additional information. 

Close box. This is a box the size of a single character, lo- 
cated at the left side of the title bar. It allows the user to close 
the window. 

Full box. This is a single character located in the right 
comer of the title bar, which allows the user to expand the 
window to full-screen size or to retract it to its original size 
and position. 

Horizontal and/or vertical slide bars. These bars stretch 
across the bottom or right window borders. They contain a 
rectangle called a slider with optional arrows at either end. 

The arrows are used to move through the contents of the win- 
dows a single character at a time, while the slider is used to 
scroll the window contents in arbitrary increments. It is also 
possible to move through the window a page at a time by 
clicking on the part of the bar located between the slider and 
the arrows. 

Note that in most cases, the AES itself does not respond 
to the user's request. For example, the AES does not close the 
window when the user clicks on the close box nor size it 
when the user drags the size box. Instead, it sends a message 
to the program, notifying it of the user's actions. The AES 
message system will be discussed in Chapter 3. 

The rest of the window — the area inside the borders — is 
the application's work space. Windows appear to divide the 
screen into separate areas, but these divisions are only logical 
constructs, not physical fact. GEM provides the framework for 
windowing, but it's up to the AES and the application pro- 
gram to actually manage the windows and their contents. The 
AES is responsible for drawing and maintaining the window 
borders and the controls placed within them. The application 
is responsible for everything that goes on inside the work 
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space. The program must keep track of the size and position 
of the active (topmost) window, and make certain that it re- 
stricts its output to the confines of the work area. Otherwise, 
the window's borders would be no more substantial than lines 
drawn on the screen. 

Window Creation 

The first step in displaying a window is to define its maximum 
size and composition with the Window library call wind—create( ). 
This function causes the AES to allocate a window and initial- 
ize the data that the AES uses to keep track of the window. It 
doesn't display the window. The format for the wind_create( ) 
call is 

int wi_ handle, controls, fullx, fully, fullw, fullh; 
wi handle = wind— create(controls, fullx, fully, fullw, fullh); 

where controls is a bit flag which tells the AES which of the 12 
window controls to attach to the window. Each of the window 
controls is assigned a bit. If the bit that represents a particular 
window control is set to 1, that control will be attached to the 
window. The 12 possible window attributes are as follows: 


Bit 

Bit Value 

Macro Name 

Window Control 

0 

1 (0x001) 

NAME 

Title bar 

1 

2 (0x002) 

CLOSER 

Close box 

2 

4 (0x004) 

FULLER 

Full box 

3 

8 (0x008) 

MOVER 

Move bar 

4 

16 (0x010) 

INFO 

Information line 

5 

32 (0x020) 

SIZER 

Size box 

6 

64 (0x040) 

UPARROW 

Up-arrow for vertical scroll 
bar 

7 

128 (0x080) 

DNARROW 

Down-arrow for vertical 
scroll bar 

8 

256 (0x100) 

VSLIDE 

Slider for vertical scroll bar 

9 

512 (0x200) 

LFARROW 

Left arrow for horizontal 
scroll bar 

10 

1024 (0x400) 

RTARROW 

Right-arrow for horizontal 
scroll bar 

11 

2048 (0x800) 

HSLIDE 

Slider for horizontal scroll 
bar 
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Since each control is represented by a separate bit, any or 
all of the controls can be attached to a given window. To cre- 
ate a window that has a title bar, a close box, and a size box, 
you would set control to a value of 35 (1 + 2 + 32). C pro- 
grammers can take advantage of the fact that the header file 
GEMDEFS.H which comes supplied with most C compilers 
contains macro definitions that give names to each of the con- 
trols. If your program starts with the directive #include 
<gemdefs.h>, you could create a window with the same set of 
controls specified above by setting controls to (NAME I 
CLOSER I SIZER). This expression still equals 35, but it's much 
easier to understand what the window attributes are when you 
look at it. 

The other input parameters you must pass to 
wind_create( ) are the window's maximum dimensions. This 
isn't necessarily the size to which the window will be 
drawn — that's determined by the wind—open( ) call, as you'll 
see. Since a window's size may be changed under program 
control, this set of parameters is used to specify the largest 
possible size to which it may be changed. This is usually equal 
to the size of the Desktop window's work area, that is, all of 
the display area except for the menu bar at the top of the 
screen. The procedure for finding out the dimensions of the 
Desktop window's work area will be discussed below. Note, 
however, that the AES doesn't limit your window size to the 
size of the Desktop work area. It's possible, for example, to 
create a window whose work area fills the entire display 
screen. Such a window will have no visible distinguishing 
marks, since the border and control boxes are out of the range 
of display memory and cannot be drawn. 

The wind_create( ) call uses the standard AES system for 
specifying the size and position of a window or other rectan- 
gle. The four values used to delimit the rectangle are its hori- 
zontal (x) coordinate, vertical (y) coordinate, width, and 
height. Those of you who are familiar with the VDI will notice 
that this system is different from the one used to describe a 
rectangle to the VDI. In that system, a pointer to an array 
holding the x and y coordinates for two opposite comers of 
the rectangle is used. For example, you might describe a VDI 
rectangle by specifying that its top left comer is at coordinate 
10,10, and its bottom right comer is at 109,109. For purposes 
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of the AES, you would describe that same rectangle by saying 
that its origin is at 10,10, and its width and height are each 
100 units. Each system has its advantages. The VDI system 
may be a bit quicker to use for drawing, since all of the co- 
ordinates are spelled out. The AES system is more flexible, 
however, since to move the rectangle you need only change 
the coordinates of the point of origin. To the programmer, the 
most important aspect of the difference between the two sys- 
tems is that some translation is required when performing VDI 
and AES operations on the same rectangle. 

Because the AES library calls frequently require a rectan- 
gle description, some programs make use of a data structure 
that includes all of the information required for such a descrip- 
tion. This structure is defined in the header file OBDEFS.H, 
which is included with most C compilers for the ST, as follows: 

typedef struct greet 

{ 

int g_x; 
int g_y; 
int g_ w; 
int g_h; 

} GRECT; 

The use of typedef means that you can declare a structure 
of the type greet either by using the declaration form 

struct greet rectangle; 

or the form 

GRECT rectangle; 

In either case, the x coordinate is denoted by 
rectangle.g_x, the y coordinate by rectangle.g_y, the width by 
rectangle.g_w, and the height by rectangle. g_h. Using such a 
data structure makes it possible to reference all the necessary 
information about a rectangle using a single variable or 
pointer. 

As the function template above shows, the wind_create( ) 
function returns a value called wi— handle. If the function suc- 
cessfully allocates a window, the value returned is a unique ID 
number, known as the window handle. This window handle is 
used to identify the window for purposes of the Window Li- 
brary routines, which can modify a window or return infor- 
mation about it. A handle of 0 is reserved for the GEM 
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Desktop window. A value in the range 1-8 is used for the 
application windows. 

If the AES is unable to allocate a new window, a negative 
value is returned in wi_handle. In the current version of GEM 
on the ST, the AES will only let you create up to eight appli- 
cation windows. This number includes the windows that are 
opened by desk accessories. If you want your program to work 
with desk accessories, leave some of the available windows for 
them. The GEM Desktop program limits itself to four win- 
dows, so that the other four can be used by desk accessories. 

If a negative handle is returned by wind_create( ), you may 
wish to display an alert telling the user to close a window and 
try again, if possible. 

As stated above, most windows are created with a maxi- 
mum size that matches that of the Desktop window's work 
area. One way of finding out the dimensions of that rectangle 
is to use the wind—get( ) function. This function can be used to 
return any of several items of information concerning a win- 
dow. Its syntax is 

int status, wi—handle, flag, x, y, width, height; 

status = wind_get(wi— handle, flag, &x, &y, &width, &height); 


where wi—handle, is the window handle returned by 
wind_create( ), which identifies the window. The next input 
parameter, flag, determines what kind of information is re- 
turned about the window. The following table shows the valid 
values for flag and the information returned by the call when 
each flag is used: 


Flag 

4 

5 

6 

7 

8 


9 

10 

11 


Macro Name 

WF—WORKXYWH 

WF—CURRXYWH 

WF_PREVXYWH 

WF—FULLXYWH 

WF—HSLIDE 


WF—VSLIDE 

WF_TOP 

WF_FIRSTXYWH 


Information Requested 
Window work area coordinates 
Window exterior coordinates 
Previous window exterior coordinates 
Maximum window exterior coordinates 
x = relative position of horizontal slider 
(1 = leftmost position, 1000 = 
rightmost) 

x = relative position of vertical slider 
(1 = top position, 1000 = bottom) 
x = window handle of the top (active) 
window 

Coordinates of the first rectangle in the 
window's rectangle list 
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Flag 

Macro Name 

Information Requested 

12 

WF—NEXTXYWH 

Coordinates of the next rectangle in the 
window's rectangle list 

13 

WF—RESVD 

Reserved for future use 

15 

WF—HSLSIZE 

x = relative size of the horizontal slider 
compared to the scroll bar (— 1 = mini- 
mum size, 1-1000 = percentage filled, 
in tenths of 1 percent) 

16 

WF—VSLSIZE 

x = relative size of the vertical slider 
compared to the scroll bar (— 1 = mini- 
mum size, 1-1000 = percentage filled, 
in tenths of 1 percent) 

17 

WF-SCREEN 

Address and length of the menu/alert 
buffers (x = low word of address, y = 
high word, width — low word of length, 
height = high word) 


Each of the values for flag has a C macro name that's re- 
lated to its function. These macros are defined in the header file 
GEMDEFS.H which is included with most C compilers. The 
flags under consideration here are the ones that return the win- 
dow size. These include WF-WORKXYWH, WF_CURRXYWH, 
WF—FULLXYWH, and WF_PREVXYWH. When any of these 
flags except WF—WORKXYWH is used, the function returns the 
size of the exterior outline of the window. This includes the 
border and any window controls located in the border, such as 
the title bar or scroll bars. When the WF_WORKXYWH flag is 
used, the function returns the size of the interior area of the 
window only. If you restrict your drawing to that rectangle, 
you'll never draw over a window border control box by mistake. 

The other flag values, which deal with such information as 
slider size and position and the rectangle list, will be covered in 
subsequent chapters. Note however, that some of these func- 
tions return values other than the standard rectangle x, y, width 
and height. In most cases, a single value is returned in place of 
the x coordinate. 

As stated above, a window handle of 0 is reserved for the 
Desktop window. Therefore, to find the dimensions of that 
window, which represents the maximum free area available for 
the applications window, you can use the call 
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#indude <GEMDEFS.H> 

int status,deskx, desky, deskw, deskh; 

status = wind_get(0,WF_WORKXYWH, &deskx, &desky, 

&deskw, &deskh); 

The Desktop window dimensions (excluding the menu 
bar) will be returned in deskx, desky, deskw, and deskh. These 
values can then be used as the input parameters for the maxi- 
mum window size in wind_create( ). The status value indi- 
cates whether or not there's been an error. If status is 0, an 
error has occurred, and if it's greater than 0, there's no error. 
Note also that if you make this call using the subcommand 
WF—CURRXYWH instead of WF_WORKXYWH, you get the 
entire screen size, including the menu bar. 
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Opening a Window 

Just creating a window doesn't cause that window to be dis- 
played on screen. For that, you must open the window using 
wind—opert( ). If, however, you specified in the wind_create( ) 
function that the window controls attached to this window 
should include either a title bar or information line, there's 
one additional step that you must take before opening the 
window: You must tell the window where to find the text for 
the information line or window title. The call to use for this 
purpose is windsetf ). The syntax for this call is 

int status, wi_ handle, field, x, y, width, height; 
status = wind_set(wi_ handle, field, x, y, width, height); 

Just as the wind_get( ) call retrieves several different bits 
of information about the window, wind_set( ) allows you to 
change various aspects of the window's appearance. Select the 
aspect you wish to change with the field parameter. This pa- 
rameter may have any of the following values: 


Field 

Number 

Name 

Aspect to Change 

1 

WF_KIND 

x = Window controls flag (same as 
controls for wind_create( ) ) 

2 

WF—NAME 

x,y = Address of string containing 
the name of the window 

3 

WF-JNFO 

x,y = Address of string for the win- 
dow's information line 

5 

WF_CURRXYWH 

Window exterior coordinates 
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Field 



Number 

Name 

Aspect to Change 

8 

WF-HSLIDE 

x = relative position of horizontal 
slider (1 = leftmost position, 
1000=rightmost) 

9 

WF—VSLIDE 

x = relative position of vertical 
slider (1 = top position, 1000 = 
bottom) 

10 

WF-TOP 

x = window handle of the top (ac- 
tive) window 

14 

WF-NEWDESK 

The address of an object tree to be 
used for the Desktop Window back- 
ground (x = low word, y = high 
word of address, width = number 
of starting object to draw) 

15 

WF—HSLSIZE 

x = relative size of the horizontal 
slider compared to the scroll bar 
(— 1 = minimum size, 1-1000 = 
percentage filled, in tenths of 1 
percent) 

16 

WF—VSLSIZE 

x = relative size of the vertical 
slider compared to the scroll bar 
(— 1 = minimum size, 1-1000 = 
percentage filled, in tenths of 1 
percent) 


Again, the macro names are synonymous with the field 
numbers defined in the header file GEMDEFS.H. A status 
value of 0 indicates that an error has occurred, while a value 
greater than 0 means no error. 

As with wind_get( ), some of the field types use fewer in- 
put parameters. The two fields of interest here, WF—NAME 
and WF—INFO require only a pointer to a text string. Since the 
pointer is a four-byte long word, it takes the place of both of 
the integer input values x and y. The format used by both of 
these calls is 

#include <GEMDEFS.H> 

static char ’string = "Window Title"; 

int wi—handle; 

wind_set(wi_handle, WF—NAME, string, 0, 0); 
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Or the following could be used since, in C, the string 
"Window Title" is treated as a pointer to a static array of the 
type char: 

wind_set(wi_handle, WF—NAME, "Window Title", 0, 0); 

Note that you must use a static array, since the AES will 
periodically look at this title in order to redraw the title bar 
when the window is sized. If the array is not permanent, the 
pointer to the string might be rendered invalid. In such a case, 
the AES might try to access an invalid string, with disastrous 
results. 

Once you've set the pointers to the window title and 
information line strings (if necessary), you're ready to open 
the window. The format for the wind—open( ) call used to per- 
form this function is 

int status, wi_ handle, x, y, width, height; 

status 1=3 wind_open(wi_liandle, x, y, width, height); 

where x, y, width, and height describe the initial exterior di- 
mensions of the window. These dimensions may be smaller 
than the full-size window described in wind_create( ), but 
they may not exceed those dimensions. The status value re- 
turns the error status of the function. A 0 indicates that an er- 
ror has occurred, while a value greater than 0 means no error. 

As with wind_create( ), the dimensions used to describe 
the window in wind_open( ) measure the exterior of the win- 
dow and include the borders and any controls located within 
those borders. Your program, however, must confine its out- 
put to the interior area of the window, so as to avoid overwrit- 
ing the window borders. You can use the wind_get( ) function 
to find the window's interior dimensions as follows: 

#indude <GEMDEFS.H> 

int status,wi_ handle,workx, worky, workw, workh; 
status = wind_get(wi_handle,WF_WORKXYWH, &workx, 
&worky, &workw, &workh); 

While wind_get( ) can be used to find the current interior 
or exterior dimensions of a window, it isn't of much help 
before you've created the window. Let's say, for example, that 
you want to open a window whose interior work area will be 
200 X 100 pixels and whose top left comer will be located at 
50,50. How can you determine the exterior dimensions of such 
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a window, in order to pass them to the wind_open( ) call? 

One way is to use the wind—calc( ) function. Given the win- 
dow control flag and either the interior or exterior dimensions 
of the window, this function can return the opposite set of di- 
mensions. Its syntax is 

int status, type, controls, knownx, knowny, knownw, knownh, 
otherx, othery, otherw, otherh; 

status = wind— calc (type, controls, knownx, knowy, knownw, 
knownh, &otherx, &othery, &otherw, &otherh); 

The dimensions of the known window area are specified 
by knownx, knowny, knownw, and knownh. The function returns 
the other set of dimensions in otherx, othery, otherw, and 
otherh. Type is a flag byte showing what type of conversion to 
perform. A 0 value means to consider the known dimensions 
to be the interior area, so that the function returns the exterior 
dimensions. A value of 1 causes the function to return the in- 
terior dimensions of the window. 

The controls input parameter is the same type of flag used 
by wind_create( ) to indicate the types of controls to attach to 
the window. These are significant to calculating the size of the 
window because their presence may enlarge the border area. If 
a window has a close box, title bar, move bar, or full box, this 
extends the border area at the top of the box to the height of a 
character box of the default character set. This is the value re- 
turned in the chboxh variable by the graf— handle( ) call. If the 
window has an information line, the top border is enlarged by 
the height of an additional character cell. If there is a vertical 
slider, or up or down arrows, the right border is extended to 
the width of the default character cell. This value is returned 
in the chboxw variable by the graf— handle( ) call. Finally, if 
there's a size box, horizontal slider, or right or left arrows, the 
bottom border is extended to the height of the default charac- 
ter cell. 

Closing a Window 

When you're through using a window for displaying out- 
put, you may close it using wind—close( ). The format for this 
call is 

int wi_ handle, status; 

status = wind— close(wi_ handle); 
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where status contains the error status of the call (0 means 
there was an error, while a value greater than 0 indicates no 
error). Wind_close( ) removes the window's display from the 
screen by sending a message to the other windows on the 
screen to update their display. If the window wasn't covering 
any application windows, its image is replaced by the Desktop 
background. While wind_close( ) removes the window display 
from the screen, the window remains allocated, and may be 
reopened at any time by a call to wind_open( ). In order to re- 
move the window completely, you must call wind—delete( ) as 
follows: 

int wL-handle, status; 

status = wind— delete(wi_ handle); 

Once you've deleted a window, you must use 
wind— create( ) to reallocate it before you can open it again. 
You should always remember to close and delete all of your 
windows before your program terminates. Closing them will 
remove their image from the screen, and deleting them will 
return the resources they use to the system. 

A C Program Shell 

Since most of the subsequent example programs use much of 
the same program code for initialization and cleanup, it would 
be repetitive to include the text of that code in every example. 
Instead, the steps necessary to open a virtual workstation and 
a window are listed below, in the form of a short program 
named aesshell.c. All this program does is perform AES and 
VDI initialization, open a window, call a function named • 
demo, close the window and exit. 

A few things are missing from this shell, however, so the 
program will not link properly or run unless you add them 
yourself. You have to add the function named demo, and macro 
definitions for the window characteristics WDW—CTRLS, 
APP— NAME, and APP_ INFO. The example will accomplish 
this through the use of the C #include directive to include the 
file aesshell.c at the beginning of most of the sample pro- 
grams. The main function of the sample program will be 
called demo( ), and there will be macro definitions for the 
window characteristics. For example, to create a program that 
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does absolutely nothing but open a window and wait for the 
user to click on its close box, you could use the code in Pro- 
gram 2-1. 

Program 2-1. dummy.c 

/t ***************** tttttt **>*>>>*>*>*** «***> >*»«*»*** tttttttttt****/ 


/* */ 

/% DUMMY.C — A short calling program that uses the »/ 

/ * program template AESSHELL.C. It defines the t/ 

ft window name and the window controls to be included. %/ 

ft It then waits a while, and exits. */ 

ft %/ 

ft */ 


/ttttttttttttttttttttttttttttttttttttttttttttttttxtttttttttttttttttf 

♦♦define APP_INFO " tt Click on the Close Box to exit the program. **“ 
♦♦define APP_ NAME "Dummy Title" 

♦♦define WDW.CTRLS (NAME I CLOSER I INFO) 

♦♦include "aesshel 1 . c" 

demo () 

< 

int msgbufCQDj 

ovnt_mesage f&msgbuf ) j ft skip the window redraw message, */ 
evnt.mesage (Scmsgbuf ) ; ft it wait for the window close message %/ 





) 


Keeping the initialization code in a reusable file will 
shorten the sample listings substantially, and eliminate retyp- 
ing. Be sure the file aesshell.c is stored where your compiler 
can find it, either in the same disk and directory as your 
standard header files or in the same disk and directory as the 
source-code file. Program 2-2 is the text of the aesshell.c pro- 
gram shell. 

Program 2-2. aesshell.c 




/* */ 

. * AESSHELL.C Program template to be included with */ 

/* most of the AES example programs. Performs init- */ 

/’* i all rat ion functions, calls the demo program, */ 

ft then does the cleanup work. %/ 

/t %f 


/ ***** »*»****«******* ******************* *********************«*****/ 


^include <osbind.h> 
^include ‘,gemdefs.h; 
♦♦include <obdefs.h> 


/* Macro definitions for BIOS calls */ 

/* Flag definitions for Library routines */ 
ft Object definitions */ 


ttdefme DESK 0 
♦♦define NO_ERR 0 
♦♦define APP_ERR 1 
(♦define VWK_ERR 2 
♦♦define WDW_ERR 3 


/* 

/* 

/* 

ft 

ft 


The flag for the Desktop 
Error no. for "no error" 
Error no. for failure of 
Error no. for failure of 
Error no. for failure of 


Window */ 

*/ 

appl_init() */ 
v_opnvwk<) */ 
wi_create<) */ 




n 

n 

n 
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U 

U 

u 


/% Global variables — For VOX bindings and program routines %/ 

extern int gl_apid; /* The application ID part of the global array */ 
int ap_id; 


int contr 1 C 123, 
intinC 1283 , 
ptsinC 1283, 
intout C 1283 , 
ptsoutC 1283; 

int phys_handle, 
handle, 
wi_handle; 


ft VDI data arrays */ 


/% workstation handle for physical screen device */ 
ft workstation handle for virtual screen device */ 
/* window handle i / 


int work_inC 123 , ft input and output arrays for v.opnvwkO tf 
wor k_out CS7 3 ; 


GRECT desk, work) /* Desktop and application window dimensions tf 


int cellw, cellh, chspcw, chspch; ft size of default character font tf 


U 

u 

u 

u 


ft Program starts here •/ 


mai n ( ) 

int error | ft Error flag */ 


error = init_all(); 

if (! error) demoO; 
cleanup (error) ; 


ft Initialize application, open workstation, tf 
ft and open application window tf 
ft If no initialization failures, run demo tf 
ft Close window, workstation, and application tf 


> 


ft Initialize application, open graphics workstation, and open window tf 

init all C) 

< 

int x; 

int pointsC43; 

ft Initialize the GEM application* If this fails, return error code. */ 

appl_init(); 
ap id=gl apid; 

if <ap_id=-l) return (APP_ERR) | 

ft Initialize input array, get the physical workstation handle, 
and open the Virtual Screen Workstation for VDI calls, tf 

handle = phys_handle = graf_handle(&cellw, &cellh, &chspcw, &chspch) ; 

ft get physical screen device handle tf 
wor k_inC 103=2; ft use Raster Coordinates */ 

work - inC03=8etrez 0+2; ft set screen device ID according to */ 
ft resolution mode. tf 
for <x=l; x<10; work_inCx++3=l) ; 

ft set other input values to default */ 
v_opnvwk <work_in, Schandle, work.out); 

ft open virtual screen workstation tf 
if (handle == 0) return (VWK_ERR) ; 

/t if we can't open it, return error code tf 
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/* Find out the maximum size for a window, and open one. */ 

wind.get (DESK, WF.WGRKXYWH, Stdesk. g_x, Stdesk. g.y, 

Stdesk. g.w, Stdesk . g.h) ; 

ft find dimensions of Desktop Window */ 
wi .handle = wind.croato (WDW_CTRLS, desk.g.x, desk. g.y, 
desk . g_w, desk . g_h ) j 
ft Create a window that size tf 
if (wi.handle<0> return (WDW.ERR) ; 

ft if we can’t, return error code tf 
wind set (wi.handle, WF.INFO, APP_INFO,0,0> ; 
wi nd.set ( wi .hand 1 e, WF.NAKE , APP.NAME , 0 , 0 ) ; 

ft set name and info string for window */ 
wind.open <wi. handle, desk.g.x, desk.g.y, desk.g.w, desk. g.h); 

ft open the window to full size tf 





ft Clear the work area of the window */ 


wind.get (wi. handle, WF.WORKXYWH, Scwork.g.x, Stwork.g.y, 
Stwork.g.w, Stwork.g.h); 

/* find out the size of its work area tf 


graf .mouse (M.OFF , 

0L) ; 

/* 

cl ear.rect (Stwork) 

i 

/* 

graf .mouse (ARROW, 

0L) ; 

ft 

graf .mouse (M.ON, 

0L) ; 

ft 

return (0) ; 


ft 


ft Close and delete window, close 


turn the mouse pointer off */ 
clear the area tf 

change the painter to an arrow tf 
and turn it back on */ 

Report no errors tf 


workstation, exit application tf 


cleanup (error ) 
int error; 

< 

switch (error) /* Perform as much cleanup as is warranted */ 

/* by the error level . Each higher level tf 
ft falls through to subsequent lower levels */ 

i 

case NO.ERR; ft if no error, close window tf 

wind.close (wi.handle) ; 
wind_delete (wi .handle) ; 

case WDW.ERR: ft If couldn't create window, close workstation */ 

v_clsvwk (handle) ; 

case VWK.ERR: /* If workstation didn’t open, exit app tf 

appl.exit ( ) ; 

case APP_ERRs ft if appl.initO failed, exit immediately */ 


ft >>>>>>>^>>>>>>>^>>> Some Handy Functions <<<<<<<<<<<<<<<<<< */ 




cl ear.rect (r ) ft clear a rectangle to the background color */ 
GREET tr ; 

int pointsE4]; 

vsf. interior (handle, 0) ; 
grect.conv (r , Scpoints) ; 
vr_recf 1 (handle, points); 
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groct_conv(r, array) /* convert greet to an array of points */ 
GRECT «rj 
int tarray; 

*array++ ** r->g_x$ 
tarray++ = f->g_y) 

*array++ =» r — >g_x ♦ r->g_w - 1 ; 
larray = r->g y + r->g_h - 1; 

> 

This program is divided into three parts. The first, 
init—all(), registers the GEM application, opens a Virtual 
Screen Workstation for possible VDI calls, and then creates 
and opens a window. It uses the VDI function vr—recfl( ), dis- 
cussed in Volume 1 of this series, to dear the work area of the 
window. And it uses the graf—mouse( ) function to turn off the 
mouse pointer and change its shape (the graff_mouse function 
will be discussed in greater detail later). 

If the essential initialization steps are not completed suc- 
cessfully, init_all( ) returns the appropriate error code. If no 
error occurred, the user-supplied demo( ) routine is executed. 
Finally, the cleanupO module closes and deletes the window, 
closes the workstation, and exits the program. 

A Machine Language Program Shell 

Setting up a bare-bones machine language program is more 
involved than just translating the corresponding shell.c pro- 
gram. For one thing, C programs usually link in a startup file 
at the beginning of the program to take care of such mainte- 
nance chores as allocating RAM for a program stack, setting 
the stack pointer to the address of that that stack, and return- 
ing any unused RAM to the pool of free memory. Programs 
written with Alcyon C link in the file appstart.o or gemstart.o 
at the beginning to take care of these tasks, and Megamax C 
programs get the necessary code from a library module called 
init.o, the source code for which is supplied in a file called 
init.c (it uses the inline assembly commands). But machine 
language programmers must provide the equivalent functions 
for each of their programs themselves. 

The other problem is that not all assemblers have an in- 
clude directive, so you won't be able to include the text of the 
shell program in each of our demo programs. Instead, assem- 
ble the shell program separately and link the resulting object 
file with the demo program object files. 

Since the shell program refers to the demo subroutine in 


39 



CHAPTER 2 


the demo program file, and the demo programs refer to the 
VDI data arrays defined in the shell program, use the .xdef 
and .xref directives to help resolve these external references. 
The .xref directive tells the assembler that the symbol is de- 
fined in another object file, while .xdef tells it that this symbol 
will be used by another object file. 

All of the machine language examples in this book have 
been created to be assembled with the Megamax C compiler. If 
you have the Alcyon compiler, use this short batch file to as- 
semble the machine language programs with Alcyon. 

as68 -1 -u %l.s 
link68 [u] %1.68k=%l 
relmod %1 
rm %1.68k 
rm %l.o 
wait %1 

Type in this file with your editor and save it to disk with 
the filename AES.BAT. 

Next, call the batch environment by double-clicking on 
the Alcyon system file BATCH.TTP. For parameters, type AES 
filename, where filename is the name of the source file you 
want to assemble. 

Program 2-3 is the assembler shell program, aesshell.s. 
Program 2-3. aesshell.s 

************************************************************ 

* * 

* AESSHELL.S — Shell program to be linked with all * 

* assembly language example programs. * 

I * 

***************** ******************************************* 


*** Program equates 


bpadr 

d 

4 

* 

Stack offset to base page address 

codelen 

a 

12 

* 

Base page offset to Code segment length 

datalen 

a 

20 

* 

Base page offset to Data segment length 

bsslen 

= 

28 

* 

Base page offset to BSS segment length 

stk 

= 

*400 

* 

size of our stack (IK) 

bp 

St 

*100 

* 

size of base page 

setbl k 

o 

*4a 

* 

command number of SETBLOCK function 

aescode 

s 

*c8 

* 

command number for AES call 

vdicode 

s 

*73 

* 

command number for VDI call 


*** External references 
** Import: 

.xref demo * the external demo subroutine. 
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. xref wdwctrl 

.xref wdwtitl 

• xref wdwinfo 

** Exports 

•xdef aes 

.xdef vdi 

.xdef pwkhnd * the phyusical workstation handle, 

.xdef vwkhnd * virtual workstation handle, 

•xdef wdwhnd * window handle, 

•xdef contrl0 * all of the VDI data arrays 

•xdef contrll 

•xdef contrl 2 

.xdef contrl 3 

.xdef contrl 4 

.xdef contrl5 

•xdef contrl 6 

.xdef contrl7 

.xdef contrl 8 

.xdef contrl9 

■xdef contrl 10 

.xdef contrl 11 

.xdef intih 

.xdef intout 

.xdef ptsin 

.xdef ptsout 

.xdef ctr 10 * all of the AES data arrays 

.xdef ctrll 

.xdef ctrl 2 

.xdef ctrl3 

.xdef ctrl4 

.xdef aintin 

.xdef aintout 

•xdef addrin 

•xdef addrout 

.xdef global 

.xdef apid 

•xdef chboxw t and miscellaneous work variables 

•xdef chboxh 

•xdef cellw 

•xdef cellh 

•xdef deskx 

.xdef desky 

•xdef deskw 

.xdef deskh 

•xdef workx 

.xdef worky 

•xdef workw 

•xdef workh 


u 

u 


Ml Program starts here. 6et base page address in aS 
. text 

move. 1 a7,a5 * save a7 so we can get the base page address 

move. 1 bpadr(aS),aS * a5 = basepage address 

t** Calculate the total amount of memory used by 
*tt our program (including stack space) in d0 


U 

u 


move. 1 
add. 1 
add. 1 
add. 1 


* total memory used a 

codelen <a5) ,d0 * length of code segment 
datalen <aS) ,d0 * + length of data segment 

bsslen (aS) , d0 t + length of uninitialized storage segment 
#stk+bp,d0 * + (size of the base page + our stack) 


41 



CHAPTER 2 




*** Calculate the address of our stack 
*** and move it to the stack pointer (a7) 


* 

move. 1 d0,dl 
add.l a5,dl 
and . 1 #-2, d 1 

* 

move.l dl,a7 

* 


t stack address = 

* size of program memory 
t + program's base address, 

* pick off odd bit to make sure that the 

t stack starts on a word boundary (it must). 

* set stack pointer to our stack 

* which is stk bytes above end of BSS 


Use the SEMDOS SETBLOCK call to reserve the area of memory 
ttt actually used for the program and stack, and release the 
*** rest back to the free memory pool . 


move. 1 

* 

move. 1 

t 

cl r . w 
move 

* 

trap 
add. 1 


d0, - <sp) 
a5, - <sp) 

- <sp) 

#*4a, - <sp) 
#1 

#12, sp 


* push the size of program memory 

t (first SETBLOCK parameter) on the stack. 
t push the beginning address of the 

* program memory area (2nd SETBLOCK parameter). 

* clear a dummy place-holder word 

* finally, push the GEMDQS command number 

* for the SETBLOCK function 

* call GEMDOS 

* and clear our arguments off the stack. 


*** Initialize the application with appl_init 


move. 1 

move. 1 

move. 1 

move. 1 

move 

move 

move 

move 

move 

jsr 


#0, resvl 
#0, resv2 
#0, resv3 
#0,resv4 
#10, ctr 10 
40, Ctrl 1 
#1 , ctr 1 2 
40, ctr 1 3 
#0, ctr] 4 
aes 


* clear global variables 


* command =* appl_init 

* no integer input parameters 

* 1 integer output parameter 

* no address input parameters 

* no address output parameters 

* do the call 


cmpi #SFFPT,apid * check to see if init failed 

beq apperr * and exit if it did 


*** Get the physical screen device handle from graf_handle 

move #77, Ctrl 0 * command = graf_handle 

move #5, ctr 12 t 5 integer output parameters 

jsr aes * do the call 

move aintout , pwkhnd * save handle and char sizes 

move aintout+2, cel 1 w 

move ai ntout+4 , cel 1 h 

move aintout+6, chboxw 

move aintout +G, chboxh 


*** Open the Virtual Screen Workstation <v_opnvwk> 


move 

move 

move 

move 


#100,contrl0 t opcode to contrl (0) 
#0,contrll t no points in ptsin 

#ll,contrl3 * 11 integers in intin 
aintout , contrl 6 * physical workstation 


handle to contrl (6) 


movea • 1 
move 

ini tloop: 
move . w 
dbra 


#intin+2, a0 
#8,d0 

#1, <a0) + 
d0, i ni tloop 


* destination address 

* loop counter 

* intin < 1 ) -intin (9) = 1 


□ 

n 

□ 




n 

n 

n 
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move 

#2, intin+20 

* 

intin (10) ° 2 (Raster Coordinates) 

move. w 

#4, - (sp) 

t 

push getrez command on stack 

trap 

#14 

t 

call XBIOS 

addq. 1 

#2,sp 

t 

pop command off stack 

addq 

#2,d0 



move 

d0, intin 

t 

use rez+2 as device ID 

jsr 

vdi 



move 

contr 1 6 , vwkhnd 

\ t 

save virtual workstation handle 

beq 

vwkerr 

t 

end program if it's zero 

* Find 

max window size 



move 

#104, ctrl 0 * 

command “ wind_get 

move 

#2, Ctrl 1 * 

2 ; 

Lnput integers 

move 

#0, aintin 

* 

window handle of Desktop 

move 

#4, aintin+2 

* 

WF_WORKXYWH command 

jsr 

aes 



move 

aintout+2, deskx 

$ store desk x,y,w,h 

move 

aintout+4, desky 


move 

aintout+6, deskw 


move 

aintout+8, deskh 



ttt Create a window with that max size 


move #100, ctrl 0 * command = wind_create 

move #5, Ctrl 1 * 5 input integers 

move #1, Ctrl 2 * 1 ouput integer 


move 

wdwctrl , aintin 

« 

move 

deskx, aintin+2 

* 

move 

desky, aintin+4 

* 

move 

deskw, aintin+6 

* 

move 

deskh, aintin+8 

* 

jsr 

aes 


move 

ai ntout , wdwhnd 

* 

bmi 

wdwerr 

* 


ttt set window name 


window Ctrl -flag 
max x 
max y 
max width 
max height 


save window handle 
if negative, exit program 


move #105, Ctrl 0 t command « wind_set 

move #6, Ctrl 1 * 6 input integers 

move wdwhnd, aintin * window handle 

move #2, aintin-*- 2 * subcommand = set window name 

move. 1 #wdwtitl , aintin+4 * point to title 

j sr aes 


ttt set info line 


move #3, aintin+2 t subcommand = set info line 

move.l #wdwinfo, aintin+4 t point to info text 

jsr aes 

ttt Open the window 

move #101,ctrl0 t command = wind_open 

move #5, Ctrl 1 

move #1 , ctrl2 * 1 ouput integers 

move deskx, aintin+2 * initial x 

move desky, aintin+4 t initial y 

move deskw, ainti n+6 t initial width 

move deskh, aintin+8 * initial height 

jsr aes 
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ttt Find window work area size 

move 4*104, ctr 10 * command = wind_get 

move #2, Ctrl 1 * 2 input integers 

move 4*5, ctrl2 t 5 ouput integers 

move 4*4, aintin+2 * WF_WORKXYWH command 

jsr aes 

move aintout+2, work* * store work >:,y,w,h 

move aintout+4, worky 

move ai ntout+6 , wor kw 

move aintout+8, workh 

ttt set fill color to white 

move 4*25, contrl 0 t opcode for set fill color <vsf_color) 
move 4*0, contrl 2 

move 4*1, contrl 3 

move 4*1, contrl 4 

move #0, intin * select white 

jsr vdi 

ttt turn mouse off 

move 4*78, Ctrl 0 * command = graf_mouse 

move 4*1, Ctrl 1 * 1 input integers 

move 4*1. Ctrl 2 * t output integer 

move 11256 . aint in * hide the mouse 

jsr aes 

ttt fill work area of window with white 

move 4*1 14,contr 10 t opcode for fill rectangle (vr_recfl) 
move **2.contrll 
move 4*0, contrl 3 

move 4*0, contrl 4 

move workx,d0 

move d0,ptsin 

add workw,d0 

subq 4*l,d0 

move d0,ptsin+4 
move worky, d0 

move d0,ptsin+2 
add workh, d0 

subq I*l,d0 

move d0,ptsin+6 

jsr vdi 

ttt change mouse to arrow 

move 4*0, ainti n * set mouse to arrow shape 

jsr aes 

ttt turn mouse back on 

move 4*257, aint in * show the mouse 

jsr aes 

ttt Do our demo program 
jsr demo 
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ttt Close 

the Window 


move 

#102, Ctrl 0 t 

command a wind.close 

move 

#1 , Ctrl 1 


move 

#l,ctrl2 


move 

#0, Ctrl 3 


move 

#0, ctr 14 


move 

wdwhnd, aintin 


jsr 

aes 


ttt Delete 

the Window 


move 

#103, ctr 10 t 

command « wind_delete 

Jer 

aes 


ttt Close 

Virtual Screen i 

Workstation (v_clsvwk) 

wdwerrt 

move 

#101 , contrl 0 

t opcode to contrl (0) 

move 

#0, contrl 1 

t no points in ptsin 

move 

#0, contr 13 

* no integers in intin 

jar 

vdi 


ttt Finish 

the application (appl_exit) 

vwkerr : 

move 

#19, ctrl0 

t opcode to contrl (0) 

move 

#0, Ctrl 1 


jsr 

aes 



tt* Exit back to DOS 
apperr t 

move. 1 #0, (a7) t Push command number for terminate program 

trap #1 * call GEMDQS. Bye bye! 





*** Make AES function call 

*** (after setting parameters) 

aess 

move-1 #apb,dl 
move.w #aescode,d0 
trap #2 
rts 

tt* Make VDI function call 
ttt (after setting parameters) 

vdi x 

move.l #vpb,dl 
move.w #vdicode,d0 
trap #2 
rts 


ttt Storage space for AES and VDI call parameters 

. data 
.even 
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********** VDI Data Arrays ************ 

! 1 

n 

contrl : 



contrl0: 

• ds.w 

1 


contrl 1 

.ds. w 

1 


contrl 2: 

. ds.w 

1 

n 

contrl3: 

.ds. w 

1 

contr 14: 

. ds. w 

1 

1 ^ 1 

contrlS: 

• ds. w 

1 


contrl6: 

. ds.w 

1 


contr 17: 

.ds.w 

1 

I 1 

contr 18: 

.ds. w 

1 


contrl9: 

• ds. w 

1 


contrl 10: 

• ds. w 

1 


contrl 1 1 : 

• ds. w 

1 


intin: 

. ds.w 

128 


intout : 

• ds. w 

128 


ptsin: 

.ds. w 

128 


ptsout: 

• ds.w 

128 


tttttttttttt** AES Data Arrays **************** 


Ctrl * 




ctrl0: 

.ds.w 1 



Ctrl 1 

•ds.w 1 



ctrl2: 

•ds.w 1 



ctrl3: 

.ds.w 1 



ctr!4: 

.ds.w 1 



global : 




version: 

. ds.w 

1 


count: 

. ds. w 

1 


apid: 

. ds.w 

1 


private: 

• ds. 1 

1 


tree: 

.ds. 1 

1 


resvl : 

. ds. 1 

1 


resv2: 

. ds. 1 

1 


resv3: 

. ds. 1 

1 


resv4: 

. ds. 1 

1 


aintout: 

.ds. w 

8 


aintin: 

. ds.w 

18 


addrin: 

• ds. 1 

3 


addrout: 

. ds. 1 

2 


ttt The AES and VDI parameter blocks hold pointers 


*** to the starting address of each of the data arrays 

i — i 

apb: . dc 

. 1 ctrl .global , aintin, aintout , addrin, addrout 

1 1 

vpb: .dc 

.1 contrl 

. , intin, ptsin, intout , ptsout 


ttttt* Misc variables ********* 

□ 

vwkhnd 

.ds.w 1 



pwkhnd 

•ds.w 1 



wdwhnd 

.ds.w 1 


n 

chboxw 

.ds.w 1 



chboxh 

.ds.w 1 



cel lw 

•ds.w 1 



cel lh 

.ds.w 1 


n 
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deskx 

.ds.w 

1 

desky 

. ds.w 

1 

deskw 

.ds.w 

1 

deokh 

.ds.w 

1 

workx 

. ds.w 

1 

worky 

.ds.w 

1 

workw 

.ds.w 

1 

workh 

.ds.w 

1 

.end 




xdef 

demo 

xdef 

wdwctrl 

xde-f 

wdwtitl 

xde-f 

wdwin-fa 

>:ref 

aes 


The first part of the program requires a bit of explanation. 
When GEM starts an application program (but not a desk ac- 
cessory), it allocates all of the system memory to that program. 
Therefore, if the program wishes to use the system memory- 
management calls, or any of the AES calls that themselves al- 
locate memory, it must deallocate all of the memory it isn't 
actually using, at startup time. The way to do this is with the 
XBIOS function, SETBLOCK. SETBLOCK is used to reserve a 
specific area of memory for the program and return the re- 
maining RAM area to the Operating System's free memory 
pool. In order to execute this command, you must pass the 
starting address of the area you wish to reserve and the size of 
the area. Please remember that it's only necessary to free 
memory when you start an application program. It's not nec- 
essary to do so with a desk accessory. 

Finding the starting address of program memory isn't dif- 
ficult. When you start the program, the second word on the 
stack points to that location. Finding the size of the program 
requires a little more knowledge of how program storage 
space is allocated. 

The memory area in which a program resides is known as 
the Transient Program Area (TPA). At the beginning of the 
TPA is a 256-byte segment known as the basepage. The 
basepage contains information about the size and address of 
each program segment, as well as the command line that is 
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passed to the program (these are the extra characters you type 
in when you run a TOS Takes Parameters program whose 
name ends in .TTP). After the basepage comes the actual pro- 
gram code, followed by the data area and the BSS (Block Stor- 
age Segment), which is used to store uninitialized data. To 
find the total size of the program area, look in the basepage 
area to find the size of the code. Add that to the size of the 
data and BSS segments, along with the size of the basepage it- 
self. Since you need a stack area for the program, it makes 
sense to add the size of the stack to the end of the program 
and reserve the combined program and stack area together 
(Figure 2-2). Once you calculate this area, you can set the 
stack pointer to the top of program memory and make the 
SETBLOCK call. When that is done, continue on with what- 
ever your program does. 


Figure 2-2. Layout of Transient Program Area in ST Memory 


High Henory 


Low Memory 


Heap 


Stack 


BSS Segment; 


Data Segment 


Text Segment 


Basepage+28 

Basepage+24 

Basepage+20 

Basepage+16 

Basepage+12 

Basepage+8 

Basepage+4 

Basepage 


Length of BSS Segment 
Address of BSS Segment 
Length of Data Segment 
Address of Data Segment 
Length of Text Segment 
Address of Text Segment 
Address of End of TPA+1 
Base Address of TPA 


OEnd of TPA 
OStack Pointer 


Start of TPA 
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In order to assemble the aesshell.s program with the 
Alcyon assembler, invoke the as68 assembler with the follow- 
ing command: 

as68 -u -1 aesshell.s 

This creates an object file called aesshell.o. Since this pro- 
gram does not contain the demo subroutine or the window-def- 
inition constants, it won't link and run properly. In order to 
get it to function, you must create another object module that 
contains that subroutine. An example of this is Program 2-4, 
dummy.s. 

Program 2-4. dummy.s 

* * 

* DtiMrtv.S Just waits for user to clicM close box * 

* * 
********************************************************* 

*** External References 


** Export: 


.xdef demo 

-xdef wdwctrl 

.xdef wdwtitl 

•xdef wdwinfo 

*t Import: 

.xref aes 

.xref ctrl0 

.xref ctril 

.xref ctrl2 

-xref Ctrl 3 

.xref ctrl4 

.xref addrin 

. text 

demos 

jar demol 
jsr demol 


demol: 

move 

move 

move 

move 

move 

move.l 

imp 


423,ctrl0 

40, Ctrl 1 

#1 , ctr!2 

41 f ctrI3 

40, ctrl4 

ttmsgbuf , addrin 

aes 
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ttt Storage space and data constants 

.data 

.even 

msgbuf : . ds . w 8 

wdwtitls .dc.b ’Test Window’, 0 
wdwinfo: -dc.b 'Info Line’,0 

wdwctrl : . dc.w 55 


• end 


Assemble this file in the same way to create the dummy.o 
file. Next, use the linker to join the two object modules. The 
command line to use is 

link68 [u] dummy.68k=aesshell,dummy 

This creates the dummy.68k file, a program module that 
must be modified to run under GEMDOS, using the relmod 
program: 

relmod dummy 

This produces the dummy.prg program file that can be ex- 
ecuted from the desktop. You may have noticed that the 
source code for the assembler shell program is about twice as 
long as that of the C shell program. But depending on what 
compiler you use, the executable program generated by the as- 
sembler version is at least 50-percent smaller than the C pro- 
gram. In order to reduce the size of the assembler source code, 
a number of shortcuts were used. Since you know the contents 
of the AES data arrays like Ctrl (the name given to the control 
array) at any given time, you don't need to fill each member 
for each function call. For example, since the input parameters 
for the graf—tnouse( ) call used to change the mouse form to an 
arrow are almost exactly the same as the ones used for the 
graf_mouse( ) call that turns the mouse back on, the only in- 
put variable that is changed between the two calls is aintin 
(the name given to the first element of the int—in array). 


> 
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AES Events: 
Windows, Part 2 





Ill older, single-tasking microcomputer systems, it's 
common for a program to check for input from the user by 
polling the input devices. That means the program sits in a 
loop, continuously checking the device until something hap- 
pens. It's sort of like having a telephone without a bell — you 
have to pick it up every few seconds in order not to miss any 
calls. In a single-tasking system, this kind of programming is 
appropriate, since the processor literally doesn't have anything 
else to do. But in a multitasking system — even a limited 
multitasking system such as GEM — such programming tech- 
niques aren't adequate. While one task sits and waits, all of 
the other tasks are slowed down or shut out completely. For- 
tunately, GEM provides a much better method of waiting for 
input, known as event-oriented waiting. 

Using the AES Event Library routines, a program tells the 
AES that it must wait until a specified event happens. The 
multitasking kernel then puts the program on the Not-Ready 
list and lets the other tasks that are on the Ready list share the 
processor's time. After the specified event occurs the kernel 
puts the program back on the Ready list and lets it execute 
again. 

The AES Event Library allows the program to wait for a 
number of different types of I/O events. These include the 
usual types of direct input from the user, such as typing on 
the keyboard, moving the mouse, and clicking a mouse but- 
ton. These I/O events also include a more sophisticated, indi- 
rect type of input, called a message. The Screen Manager sends 
these messages to let the program know that the user has per- 
formed a significant action, such as clicking on a window's 
close box or full box, or selecting an item from a drop-down 
menu. Messages may also be generated by system events, 
such as the window-redraw messages that are sent when a 
window's graphics have been damaged by moving or sizing 
other windows. The system timer may be used to generate an 
event after a specified length of time. 

Since most programs need to check for more than one 
type of event, a function called evnt—multi( ) is provided. 
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which may be used to wait for any combination of events. In a 
typical GEM program, the main program loop centers around 
an evnt_multi( ) call, and the various routines that are used to 
handle the events returned by this call. 

Message Events 

In order for a multitasking system such as GEM to be really 
effective, there has to be a way for tasks to communicate with 
one another, so that there's an orderly division of labor. GEM 
provides a message system for intertask communication. Each 
task has its own message pipe, in which messages are stored 
in FIFO (First In, First Out) order. When a task asks for its 
messages, the top one is taken from the pipe and moved to a 
buffer which the task designates. The message pipe can hold 
up to eight 16-byte messages at a time. 

When an applications wants to wait for a message, it uses 
the evnt-.mesag( ) call, whose format is as follows: 

int reserved, msgbuf[8]; 
reserved = evnt_ mesag(msgbuf); 

where the tnsgbuf array is a temporary storage buffer in which 
the 16-byte message is deposited. The reserved variable is al- 
ways equal to 1. The fact that a reserved variable is provided 
indicates that this function may return some significant value 
in the future. 

If messages are already waiting in the message pipe, the 
evnt_mesag( ) call will return immediately with the first one. 

If there are no messages in your program's message pipe, a 
call to evnt_mesag( ) will force your program to wait until one 
is received. 

The values actually placed in the msgbuf array depend on 
the type of message sent. The format for the first three words 
of each message is standardized: 

Element 

Number Contents 

0 Message ID (indicates type of message) 

1 Application ID of message sender 

2 Number of additional bytes in message (in excess of the 
standard 16) 

3-7 Message-dependent 


54 



AES Events 


The contents of the last five words of the message vary, 
depending on the message type. Although the standard GEM 
message is only eight words long, it's possible to send a longer, 
user-defined message to another task using the appl—write( ) 
function. That's why the third word of the standard message 
format contains the number of additional bytes in the mes- 
sage. To receive the rest of the message, the task must read 
the message pipe directly, using the appl—read( ) function, 
which will be discussed later on, along with appl_write( ). 

There are 13 predefined AES messages, which the Screen 
Manager task sends to the application. These are as follows: 


Message 



Number 

Macro Name 

Message Sent 

10 

MN-SELECTED 

A menu item was selected by the 
user 

20 

WM—REDRAW 

A window display needs to be 
redrawn 

21 

WM—TOPPED 

The user has selected a new window 
to be active 

22 

WM-CLOSED 

The user has clicked on the close 
box 

23 

WM-FULLED 

The user has clicked on the full box 

24 

WM-ARROWED 

The user has clicked on the scroll 
bars or arrows 

25 

WM_HSLID 

The user wants to move the horizon- 
tal slider 

26 

WM—VSLID 

The user wants to move the vertical 
slider 

27 

WM_SIZED 

The user has dragged the size box 

28 

WM_MOVED 

The user has dragged the move bar 

29 

WM—NEWTOP 

A window has become active 

40 

AC-OPEN 

A desk accessory has been selected 
from the menu 

41 

AC-CLOSE 

An application has closed, and desk 
accessories have lost their handles 


The macro definitions for the names of the various mes- 
sage ID's can be found in the header file GEMDEFS.H that 
comes with most C compilers. As you can see, 10 of the 13 
start with the letters WM, which mean that they are window 
messages. Since these messages tell the other half of the win- 
dow-management story started in the previous chapter, they 
will be discussed in detail here. The other three predefined 
messages, dealing with menus and desk accessories, will be 
covered along with those subjects later. 
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Window Display Refresh Messages 

Perhaps the most important message your program can expect 
to get is WM—REDRAW. Most computer applications expect to 
update the screen display from time to time, to reflect changes 
in the information which the program outputs. But any appli- 
cation which takes advantage of the full range of GEM fea- 
tures must be ready to redraw the contents of each of its 
windows at any time. 

Because of the nature of the GEM windowing system, all 
or part of a window might be covered or uncovered at any 
time. When that happens, the AES takes care of redrawing the 
window border areas, but it's up to the application to redraw 
the interior display of each of its affected windows. 

You may expect to receive a WM—REDRAW message 
even if your application has only one window and that win- 
dow has no window controls for moving or sizing it. The rea- 
son for this is that as long as your window includes a menu 
bar, you might start up a desk accessory that opens windows 
of its own. Your program can expect a window redraw mes- 
sage in any of the following circumstances: 

• A new window is opened on the screen. 

• Windows are reordered by sending a new window to the top 
of the stack as the active window. 

• A window is made larger in any dimension. 

• A window is moved from a position part way off the screen 
to a position where more of the window is on the screen. 

• A window is closed, sized down, or moved, exposing a previ- 
ously covered portion of another window. This window 
doesn't have to belong to your program. It may have been 
opened by another task, such as a desk accessory. 

• A dialog is completed, and the dialog box is removed. 

When these or similar events occur, the Screen Manager 
determines which portion of the screen display has been dam- 
aged, and notes the size and position of the rectangle enclos- 
ing this area. Then it checks each open window to see if any 
portion of the window's work area overlaps that rectangle. It 
then sends the application a separate redraw message for each 
window that needs to be refreshed. The format for this mes- 
sage is as follows: 
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Word 

Number Contents 

0 20 (WM—REDRAW), the message ID number 

3 The handle of the window whose display needs 
refreshing 

4 The x position of the damaged rectangle 

5 The y position of the damaged rectangle 

6 The width of the damaged rectangle 

7 The height of the damaged rectangle 

When your program receives the WM—REDRAW message, 
there is a set pattern of steps that you must take to restore the 
contents of that window. First, you must stabilize the state of 
the screen, so that no changes take place during the update 
process. Turn off the mouse with the graf—tnouse() call: 

gra£_mouse(M_OFF, OxOL); 

The reason for hiding the mouse pointer is that the AES 
stores the image of the rectangle underneath the mouse and 
restores that image when the mouse is moved. If you merely 
overwrite the mouse with your graphics output, the next time 
the mouse is moved the system will restore the previous im- 
age, wiping out a rectangle of your new display. The second 
part of stabilizing the screen display is to lock the screen with 
the wind— updated ) call. The format for this call is 

int status, code; 

status = wind_update(code); 

where status is equal to 0 if an error occurred. If there was no 
error, a nonzero quantity will be in status. The code value in- 
dicates the function of the call: 


Code Macro Name 

0 END—UPDATE 

1 BEG-UPDATE 

2 END—MCTRL 

3 BEG—MCTRL 


Function 

Notifies AES that the application is end- 
ing its window display update 
Notifies AES that the application is begin- 
ning a window display update 
Notifies AES that it should once more 
take control of the mouse when it leaves 
the active window area 
Notifies AES that the application is taking 
control of all mouse functions, even when 
it moves out of the active window 
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The macro names for this function are defined in the file 
GEMDEFS.H. For purposes of starting the refresh process, use 
the call: 

wind_update(BEG_ UPDATE); 

This call prevents the system from making display 
changes in the part of the screen being updated. Things could 
get very messy if a menu dropped down on top of your win- 
dow while you were drawing in it. 

Next, comes the process known as “walking the rectangle 
list." Unless your window is the active (topmost) window, it's 
possible that part of it is covered by another window. The AES 
doesn't automatically limit your graphics output to the part of 
the window that's showing. Therefore, if your program re- 
draws the entire window, it's going to destroy parts of other 
windows. 

Keeping your graphics output within the visible portion of 
your window is strictly your program's responsibility. The AES 
helps you in this task, however, by keeping what's known as a 
rectangle list. When a window is partially obscured, GEM di- 
vides the visible portion of the window into the least possible 
number of nonoverlapping rectangles. For example, if two 
windows on the screen overlap at a comer, the visible portion 
of the top window will consist of one rectangle, while the visi- 
ble portion of the bottom window will be divided into two 
rectangles. If the top window overlaps a side of the bottom 
window, the visible portion of the bottom window will be di- 
vided into three rectangles. If the top window is entirely con- 
tained within the bottom one, the visible part of the bottom 
window will be divided into four parts. As you increase the 
number of windows, the combinations increase as well. (See 
Figure 3-1.) 

To find the list of visible rectangles for a particular 
window, you use the wind—get( ) command. As you may re- 
member from the previous chapter, this command contains 
two subcommands which are of interest here. One is 
WF—FIRSTXYWH, and the other is WF—NEXTXYWH. 

WF—FIRSTXYWH returns the position and size of the first 
rectangle. WF_NEXTXYWH returns the position and size of 
the next rectangle in the list. Each subsequent call to wind_get 
with the WF_NEXTXYWH subcommand returns the position 
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Figure 3-1. Some Window Rectangle Possibilities for a Two-Window 
Screen 
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and size of the next rectangle of the list. When either type of 
wind_get( ) command returns a rectangle with a width and 
height of 0, you've reached the end of the list. 

Now that you know what the rectangle list is, here is how 
to use it in your window refresh procedure. The next step is to 
get the first rectangle in the window's rectangle list with the 
wind_get( ) call: 

wind— get 

(wi_ handle, WF—FIRSTXYWH, &wrec.g_ x, &wrec.g_y, 
&wrec.g_w, &wrec.g_h); 

Now that you have the position and size of the damage 
rectangle, and the position and size of the first window rectan- 
gle, you must check to see if the two rectangles overlap any- 
where. If they do, this third "overlap" rectangle marks the 
area whose display must be updated. 

Figuring out the overlap area is fairly simple. The x posi- 
tion is equal to the greater of the two values of the original 
two rectangles, and the y position is equal to the greater of the 
two original y values. To find the width you first find the 
lesser of the two (x + width) values and then subtract this fig- 
ure from the overlap x. To find the height, you take the lesser 
of the two (y + height) values and subtract it from the overlap 
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y. In C code, the process of finding the overlap area looks like 
this: 

#define MAX(X,Y) ( (X) > (Y) ? (X) : (Y) ) 

#define MIN(X,Y) ( (X) < (Y) ? (X) : (Y) ) 

olapx = MAX(xl, x2); 

olapy = MAX(yl, y2); 

olapw = MIN(xl+wl, x2+w2) — olapx; 

olaph = MIN(yl+hl, y2+h2) — olapy; 

If both the overlap rectangle width and height are greater 
than 0, then there's an overlap area that needs redrawing. 
Before you do the actual redrawing, however, you must set a 
clipping rectangle. Clipping confines your graphics output to 
the specified rectangle. When the drawing operation attempts 
to go outside that rectangle, nothing is output. If your program 
uses the VDI to draw the window contents, you may set a 
clipping rectangle with the VDI call vs—clip( ). This call takes 
the form: 

int handle, points[4]; 
vs_clip(handle, 1, points); 

where handle is the VDI workstation handle, and points is an 
array containing the coordinates for two opposite comers of 
the rectangle. Note that the VDI representation of a rectangle 
as an array of points differs from the AES convention of speci- 
fying one point of origin and then specifying the width and 
height. To convert from AES format to VDI format, place the 
rectangle x and y in the first two array elements, x + width — 1 
in the next and y + height — 1 in the last: 

GRECT olap; 
int handle, points[4]; 
point[0] = olap.g— x 
pointflj = olap.g_y 
point [2] = olap.g_x + olap.g— w —1 
point [3] = olap.g—y + olap.g_h —1 
vs_ clipfhandle, 1, points); 

As you will see in a later chapter, your program may also 
use the Object Library routine objc—draw( ) to draw part of the 
window contents. The input parameters for this call include 
the position and size of a clipping rectangle. When you use 
this call, therefore, you may just give the dimensions of the 
overlap rectangle as the clip area. 
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Each subsequent clipping rectangle is treated in pretty 
much the same manner as the first. You get the next clipping 
rectangle with the call: 

wind_get 

(wi_handle, WF—NEXTXYWH, &wrec.g_x, &wrec.g_y, 
&wrec.g_w, &wrec.g_h); 

If the width and height of the rectangle aren't 0 (which 
would signify that you've already received the last rectangle 
on the list), you find the overlap of the window rectangle with 
the damage rectangle. If an overlap rectangle exists, you set 
the clipping rectangle and perform the redraw. This process 
continues until there are no more window rectangles to re- 
fresh. At that point, you unlock the screen display with a call 
to wind—update( ): 

wind_update(END_UPDATE); 

This lets the AES know that it's safe to drop menus and 
so on. If you forget this call, your program won't be able to ac- 
cess any menus. After unlocking the screen, you should turn 
on the mouse with a call to graf—mouse( ): 

graf_mouse(M_ON, OxOL); 

To summarize, the steps to take when refreshing a win- 
dow display are these: 

1. Turn off the mouse with the graf_mouse( ) call. 

2. Lock the screen display with the wind_update( ) call. 

3. Get the first rectangle in the window's rectangle list with 
the wind_get( ) call. 

4. If the width and height of this rectangle are greater than 0, 
calculate the size and position of the "overlap rectangle." 
This rectangle is made up of the area where the window 
rectangle overlaps the damage rectangle. If there are no 
more rectangles in the list (the width and height values are 
0), go to step 7. 

5. If the two rectangles did intersect, redraw the overlap rec- 
tangle. If the program uses the VDI to draw the window 
contents, convert the AES rectangle to an array of points 
and set a clipping rectangle with the VDI call vs_clip( ). If it 
uses an AES object tree to draw the window contents, set 
the clip area with the objc_draw( ) input parameters. If 
there was no overlap, go on without redrawing. 


61 



CHAPTER 3 


6. Get the next clipping rectangle with wind_get( ) and go 
back to Step 4. 

7. Unlock the screen display with wind_update( ) and then 
turn the mouse back on with graf_mouse( ). 

Handling the WM_REDRAW messages takes care of the 
case where system events force you to refresh your window. 
There are circumstances, however, under which you'll have to 
redraw the window even when you don't get a system mes- 
sage. For example, you don't get a redraw message for a win- 
dow when you decrease its size, but you may want to change 
that window's contents all the same. Likewise, you don't get a 
redraw message when you move the slider in a scroll bar, but 
you'll want to change the window contents then, too. One 
way to perform the update is to simply call your window re- 
fresh routine. But another alternative is to send yourself a re- 
draw message. When the program receives this message, the 
redraw is taken care of by the normal message-handler rou- 
tine. The main advantage to sending yourself a message when 
you want to refresh a window is that the AES checks to see if 
there's already a redraw message waiting in the pipe. If there 
is, it "merges" the two requests by changing the damage rec- 
tangle to one large enough to include the two smaller damage 
rectangles. This helps prevent multiple refreshes. Such sequen- 
tial redrawings slow down the program and give it an un- 
professional, flickering appearance. 

Sending and Receiving Messages 

You send your program a message the same way you'd send a 
message to any other task. First, you create an eight-word 
message in a buffer. The standard format is used for this mes- 
sage. The first word contains the message ID, the second word 
contains the application ID of the task sending the message, 
the third contains the number of additional bytes (past the 
standard 16) used by the message, and the rest contain mes- 
sage-specific data. After creating the message, you send it by 
using the appl—write( ) function. The syntax for this function is 

int status, id, length, msgbuf[ ]} 
status = appl_write(id, length, msgbuf); 
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where id is the application ID of the task to which you are 
sending the message, length represents the length of the mes- 
sage in bytes (16 is the standard length for an eight- word 
message), and msgbuf is a pointer to the buffer which contains 
the message. The value returned in status equals 0 if there was 
an error in performing the function, and it's greater than 0 if 
no error occurred. To send a redraw message to your own 
application, therefore, you could use the following code: 


int wi_ handle /' 

GRECT r; /' 

int msg[8]; /' 

msg[0] = WM-REDRAW; /' 
message */ 

msg[l] = gl_ apid; /' 

array */ 

msg[2] = 0; / 

long */ 

msg[3] = wi—handle; / 

msg[4] = r.g_x; / 

rectangle * / 
msg[5] = r.g_y; 
msg[6] = r.g_w; 
msg[7j = r.g_h; 


appl_write(gl_apid, 16, &msg); 


The handle of the window to be 
redrawn */ 

The redraw rectangle */ 

The message buffer */ 

Message type is window redraw 

Application ID stored in Global 

Message is standard 16 bytes 

Handle of window to refresh */ 
Position and size of redraw 


Sending a message to your own application is easy, since 
a program can always find its own application ID by looking 
in the global array. To send a message to another application, 
however, you must first find its application ID, using the func- 
tion appl—find( ). The syntax for this function is 

int id; 

char name[8]; 

id = appl— find(name); 

where name is a null-terminated string containing the filename 
of the application. This string must be exactly eight characters 
long; if the filename is shorter, the end of the string should be 
padded with spaces to bring it to eight characters. The applica- 
tion's ID is returned in the variable id. If GEM can't find the 
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application, a value of — 1 is returned. 

If you want to wait for a message event, you can use the 
evnt—mesag( ) command to place the first message in your 
buffer. To read the message pipe directly, use the appl—read( ) 
command. The format for this command is 

int status, id, length, msgbuf[ ]; 
status = appl_read(id, length, msgbuf); 

where id is the application ID for the application whose mes- 
sage pipe you're reading (generally your own). Length and 
msgbuf are the length of the message (in bytes) and a pointer 
to the message buffer, respectively. The function returns a sta- 
tus value of 0 if there was an error, and it's greater than 0 if 
there was no error. Generally you'll use the appl_read( ) func- 
tion when you get a message whose third element contains a 
number greater than 0, signifying that there are more than 16 
bytes in the message. You'll use the number of bytes specified 
in the third element for the length field in appl_read. 

Messages for Moving, Sizing, or Closing a Window 

In the previous chapter, the various window control boxes 
were mentioned, such as the size box and the full box. It was 
also mentioned that these boxes do not perform the indicated 
functions autonomously. In other words, if the user clicks the 
full box, the AES doesn't automatically resize the window all 
by itself. Instead, the Screen Manager sends a message to the 
application telling it what the user has done. When the pro- 
gram gets this message, it can either ignore it or honor it by 
changing the window using the wind—set( ) function. 

If you've created a window that includes the sizer control, 
your program should be prepared to deal with message 27, 
WM—SIZED. When the user moves the mouse to the size box, 
holds down the left mouse button, and drags the mouse, the 
Screen Manager displays an elastic image of a box that follows 
the mouse, indicating the new outlines of the window. When 
the user releases the mouse button, the Screen Manager erases 
the box, and sends the application message 27. The contents 
of the msgbuf message buffer after such a message is received 
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looks like this: 

Word 

Number Contents 

0 27 (WM—SIZED), the message ID number 

3 The handle of the window that was requested to be sized 

4 The requested x position of the window's left edge (the 
same as the current window x position) 

5 The requested y position of the window's top edge (the 
same as the current window y position) 

6 The requested width of the window 

7 The requested window height 

If you're willing to let the user size the window arbitrarily, 
you can just forward the window dimensions received in the 
message to the wind_set( ) command, which will resize the 
window to those dimensions: 

wind_set 

(msgbuf[3j, WF—CURRXYWH, msgbuf[4j, msgbuf[5], msgbuf[6], 
msgbuf[7]); 

GEM itself constrains the sizing of a window to a limited 
degree. It won't allow a window larger than the screen, or so 
small that the scroll bar controls located in the window bor- 
ders are totally obscured. 

You may wish to set your own minimum and maximum 
size limits, or you may want your program to adjust the sizing 
request before passing it on to wind_set( ). For example, if 
you're working with a text-based application, you may want to 
limit window sizing to an even multiple of the default charac- 
ter-cell size or to even 16-bit boundaries. Printing graphics text 
is much faster when each line of text starts on a 16-bit bound- 
ary. Just remember that the rectangle returned by the 
WM—SIZED message describes the exterior dimensions of the 
window, including the border area. If your program is inter- 
ested in controlling the interior or work area of the window, 
use the wind— cal c( ) function to convert the requested size 
from exterior to interior size, adjust that size, and then use 
wind_calc( ) to convert back before passing the dimensions to 
the wind_set( ) call. 

A Redraw request is generated for a window when the 
wind_set( ) command is used to increase its size. In some 




CHAPTER 3 


cases, your program may want to reshuffle the display when 
the window is sized down as well. You can accomplish this 
either by calling the redraw routine directly or by sending 
yourself a redraw message after changing the size with 
wind_set( ). 

Another way the user can indicate a desire to change the 
size of the window is by clicking on the fuller box. If the win- 
dow controls flag for your window includes the fuller attribute, 
indicating that the window has a fuller box in the top right 
comer, your program should be prepared to handle message 
23, WM—FULLED. The relevant items in the message buffer 
for this message are 

Word 

Number Contents 

0 23 (WM—FULLED), the message ID number 

3 The handle of the window whose full box was clicked 

The fuller box is supposed to act like a toggle. That means 
if the window isn't at full size when the user clicks on it, it's 
supposed to expand to full size. If the window is already at 
full size when the user clicks, the window should contract to 
its previous size. As usual, it's up to you to implement this 
toggle mechanism. The AES helps out by keeping track of 
the window's current size, its maximum size, and its previous 
size. You may determine all three of these window dimensions 
by calling wind_get( ) with the appropriate subcommand 
(WF—CURRXYWH, WF-PREVXYWH, or WF—FULLXYWH). 
After you've found out the size and position of these rectan- 
gles, you can check to see if the current size equals the maxi- 
mum size. If it doesn't, you may set the window to maximum 
size using wind_set( ). If it's already at that size, you may use 
wind_set( ) to change to the previous size. The subcommand 
to use is WF_CURRXYWH: 

wind_set(wi_ handle, WF—CURRXYWH, newx, newy, neww, 
newh); 

Since you use wind— set( ) to change the window size in 
response to the WM—FULLED message, just as you do for the 
WM_ SIZED message, the same rules about redraw messages 
apply. If you increase the window size, your program will get 
a redraw message. If you decrease its size, it won't get a re- 
draw message. Therefore, if you want to redraw after making 
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the window smaller, either call the redraw routine directly or 
send yourself a redraw message after changing the size with 
wind— set( ). 

Not only may GEM windows be sized, but they may be 
moved as well. When the user places the mouse pointer on 
the drag bar, holds down the left button, and moves the 
mouse, the Screen Manager draws a dotted window outline 
that moves with the mouse. This outline shows the new win- 
dow position. When the user lets go of the mouse button, the 
Screen Manager sends the program message 28, WM—MOVED. 
Any program that has a window with the mover attribute in 
its control word should be ready to handle the WM—MOVED 
message. The significant elements of this message are 

Word 

Number Contents 

0 28 (WM_MOVED), the message ID number 

3 The handle of the window whose move bar was dragged 

4 The requested x position of the window's left edge 

5 The requested y position of the window's top edge 

6 The requested width of the window (the same as the cur- 

rent width) 

7 The requested window height (the same as the current 
window height) 

If you're willing to let the user move the window any- 
where on the screen, you can merely forward the new window 
position to the wind— set command, using the WF_ CURRXYWH 
subcommand: 

wind— set 

(msgbuf[3], WF_ CURRXYWH, msgbuf[4], msgbuf[5], msgbuf[6], 
msgbuf[7]); 

You will probably want to constrain the user's freedom to 
move windows around on the screen. The current version of 
GEM on the ST won't let you drag a window past the left or 
top screen borders, unless its starting position was beyond 
those borders. But it will let you move a window partially off- 
screen towards the bottom or to the right. Therefore, you may 
wish to prevent the user from moving the window past the 
right or bottom borders. 

To keep the complete window display on screen, make its 
maximum x position equal to the width of the Desktop win- 
dow rrunus the width of your application window, and its 
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maximum y position equal to the height of the Desktop win- 
dow minus the height of your application window. 

Another constraint on window moving that would be 
valuable to your program would be to align the left edge of 
the window on a 16-bit word boundary. By rounding the co- 
ordinates for the left edge of the window to an even multiple 
of 16, you make it easier for GEM to move the window con- 
tents quickly, since it eliminates a considerable amount of bit- 
shifting and masking operations. Aligning an image to an even 
8-byte or 16-byte boundary is known as snapping. 

Usually when you use the CURRXYWH subcommand of 
wind__set( ) to move the window, the AES will perform a raster- 
copy operation that will move the window's contents automat- 
ically. The only time you'll get a refresh message for the 
moved window is if the window is partially offscreen, so that 
the AES doesn't have access to the complete contents of the 
window. If you prevent the user from moving the window 
partially offscreen, a move operation will never generate a re- 
draw message for the window that you've moved. 

When the AES wants your application to move one of its 
windows to the top of the screen and become the active win- 
dow, it sends message 21, WM—TOPPED. This happens when 
the user selects a window to be active by clicking within its 
area, or when the current active window is closed by its appli- 
cation or desk accessory. The format for the WM—TOPPED 
message is 

Word 

Number Contents 

0 21 (WM_TOPPED), the message ID number 

3 The handle of the window the user clicked in 

When you get this message, you should move the window 
to the top. The way to move a window to the top is with the 
WF_ TOP subcommand of wind— set( ): 

int wi_ handle; 

wind— set(wi_ handle, WF_ TOP, 0, 0, 0, 0); 

Even if your application only has one window, it must al- 
ways be ready to handle the WM—TOPPED message if it has a 
menu bar, since a desk accessory may open a second window. 
If no window is made active, you may not get any messages 
from the AES, and the user may be locked out of the program. 
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When the user dicks on the dose box in the upper left 
corner of the window, the Screen Manager sends your applica- 
tion message 22, WM_CLOSED. The format for this message is 

Word 

Number Contents 

0 22 (WM—CLOSED), the message ID number 

3 The handle of the window whose close box was clicked 

When you get this message, you should take whatever ac- 
tion is appropriate. Most of the time, you'll just close the win- 
dow with wind—close( ): 

wind_close(msgbuf[3]>; 

Sometimes, you'll want to put up an alert message like 
"Are you sure? [Yes] [No]" or "Save file before closing? [Yes] 
[No] [Cancel]" to make sure that the user doesn't accidently 
exit the program and lose valuable work. Other times, the 
WM—CLOSED message indicates that the user wants to move 
back a level. For example, when you close a folder display 
window in the Desktop application, the window doesn't disap- 
pear, but rather displays the contents of the next highest sub- 
directory. This kind of ambiguity can confuse the user, so use 
caution when defining the close box to mean anything other 
than getting rid of the window. 

If you plan to allow the user to reopen the window, then 
you don't have to delete it immediately. But you should re- 
member to delete it before you close the application. 

Program 3-1, a C program, shows how to handle window 
messages that request you to redraw, size, full, close, or top a 
window. 



Program 3-1. message.c 


U 

u 

u 


/************ ************** **************************** ************/ 


/* */ 

/* MESSAGE.C — Demonstrates the various window messages */ 

/* your program might receive, and how to handle them. */ 

/* */ 

/* */ 


/******************************************************************/ 


♦♦define FALSE 0 
♦♦define TRUE 1 
♦♦define APP_INFO ”” 

♦♦define APP_NAME "First Window" 

♦♦define WDW^CTRLS <NAME I CLOSER ! SIZER ! MOVER I FULLER) 
♦♦define MAx7x,Y> < <X> > <Y> ? (X) : <Y> > 

♦♦define MIN(X,Y> < <X> < (Y) ? <X> : <Y> ) 
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^include "aesshel 1 . c" 

int wh2, msgtai; /% second window handle, message buffer */ 

demoO 

C 

int closed»0; 

wh2=wind_create(WDW_CTRLS, desk.g_x, desk.g_y, desk.g_w, desk.g.h); 

/* Create another window */ 
wind_set (wh2, WFJfAME, "Second Window", 0, 0) ; 

/* set name for window tf 

wi nd_open (wh2, desk,g_x + desk.g_w/4, desk.g.y + desk.g_h/4, 
desk.g_w/2, desk.gJi/2); 

/% open the window to half size */ 


n 

n 

n 


do /* 

C 

evnt_mesage (&msg ) ; /* 

closed +» handle msg(); /t 

> 

while (closed<2) ; /* 

wind open (wi handle, 0, 0,0, 0) ; /* 

wind .del ete < wh2 ) j /* 


main program loop t/ 

get messages* . . */ 
and handle them... */ 

til both windows are closed t/ 

open 1st wdw so shell can close */ 
delete second window */ 


handle„msg() /* message handler %/ 

t 

int closed = FALSE; 

switch <msgC03) ft check message type */ 

C 

case WM_REDRAW» /* if redraw, call refresh routine */ 

ref resh (msgC33, (GRECT *)8tmsgC43>; 
break; 


case WM_TCPPEDx /* if topped, send to top */ 

wind_set (msgC33 , WF_TCJP, 0, 0, 0, 0) J 
break; 

case WH.SIZEDx ft if sized, check for min size, 

then resize %/ 

msgC6D = MAX<msgC6D, cellwtB); 
msgC73 » MAX(msgC73, cellh*4>; 

wi nd_set (msg C33 , WF_CURRXYWH, msgC43, msgCSl, msgC63, msgC73); 

redraw_msg (msgC33 , (GRECT *)ScmsgC43); 

break; 

case WM.J10VED* ft if moved, make sure the window 

stays on the Desktop %/ 
if (msgC43 + msg C 6 3 > desk.g_x + desk.g_w) 
msgC43 » desk.g_x + desk.g_w - mag [61; 


if <msgC53 + msgC73 > desk.g_y + desk.g_h) 
msgCSl « desk.g_y + desk.g_h - msgC73; 

wind_set (msgC33 , WF_CURRXYWH, msgC41, msgtSD, msgC61, msgC71>; 
break; 

case WM_FULLED: ft if fulled, do toggle routine tf 

toggle (msg C33 ) ; 
break; 


n 

n 

n 

n 

n 
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case Wh_CL05ED: /* if closed, close window and 

increment count %f 

wind_cl ose (msgC33 ) ; 
closed = TRUE; 
break; 

default: 

break; 

> 

return (closed) ; 


toggle(wh) /* routine to handle WM_FULLED message */ 

int wh ; 

€ 

GRECT prev, curr, full; 


ft get current, previous, 
wind_get<wh, WF_CURRXY«H, 
wind_get<wh, WF_PREVXYWH, 
Mi nd_get (wh, WF_FULLXYWH, 


and full size for window %/ 
S«curr.g_x, &curr.g_y, S<curr.g_w, 
Scprev.g^x, $tprev.g_y, $<prev.g_w, 
Scfull.g_x, Stf ul 1 . g_y , S<full.g_w, 


Stcurr .g_h) ; 
Scprev. g_h) ; 
&f ul 1 . g h) ; 


ft If full, change to previous (unless that was full also) */ 
if ( ( (curr.g_x == full.g_x) SiS< 

(curr . g_y == full.g_y) S<S< 

(curr.g_w == full.g_w) 5cl< 

(curr . g_h == full.g_h>) && 

((prev.g_x != full.g_x> !! 

(prev.g_y != full.g_y> It 
(prev. g_w != full.g_w> !! 

(prev.g_h ! = full.g h) ) ) 

C 

wind_set(wh, WF_CURRXYWH, prev.g_x, prev.g_y, prev.g_w, prev.g_h>; 
redraw_msg (wh, J»prev); ft send a redraw message, cause AES won’t */ 

} 


ft If not full, change to full */ 
el se 

wind_set(wh, Wf'_C.URRXYWH, full.g_>:, full.g_y, full.g_w, full.g_h>; 





U 

U 


refresh (wh, drect) 
int wh: 

GRECT * drect; 

( 

GRECT wrect; 


/* routine to handle wi ndow_ref resh <WM_REDRAUJ) */ 
/* window handle from msgC33 */ 

/* pointer to damage rectangle #/ 

/* the current window rectangle in rect list */ 


graf _mouse <M_QFF, 0L>; /* turn off mouse */ 

wi ndjupdate (BEG_URDATE) ; /* lock screen */ 


wind_get /* get first rectangle */ 

(wh, WF_F IRSTXYWH, Stwrect . g_x , &wrect.g_y, 8twrect.g_w, &wrect . g_h ) ; 


while ( wrect. g_w 8 <8< wrect. g_h ) /* while not at last rectangle, tf 
C 


if (over 1 ap (drect , iwrect) ) 

C 

set_cl i p (Stwrect ) ; 
di spl ay ( > ; 

vs_cl i p (handle, FALSE, 


/* check to see if this one's damaged, 

ft if it is, set clip rectangle tf 
ft redraw, and turn clip off tf 
(int * ) Stwrect >; 


wind_get(wh, WF_NEXTXYWH, fcwrect . g_x , &wrect.g_y, !<wrect.g_w, 
fcwrect . g_h) ; 


> 


*/ 
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wind_update (END.UPOATE) ; 
graf _mouse <M_CN, 0X0L) ; 

> 


ft unlock screen tf 

ft turn mouse pointer back on tf 



display <> ft draw the window display tf 

< 

int pointsC43; ft VDI points array tf 


wind_get <msgC31, WF_WORKXYWH, Scwork,g_x, Scwork.g_y, 

&wcrk.g_w, &work.g_h); ft find work area */ 
clear_rect (l<work) ; ft and clear it tf 


grect.conv (&work, ^points); ft convert work greet to array tf 

vsf ^interior (handle, 2) ; ft set fill type to pattern %/ 

vsf_style (handle, 7 * msgC33 ♦ 2); ft adjust fill pattern %/ 
vsf_col or (handle, msgE33); ft set color tf 

v_el 1 ipse (handle, pointsC03 ♦ (work.g_w/2) , pointsC13 + (work . g_h/2) , 
werk.g_w/2, work.g_h/2>; ft draw a filled ellipse tf 




/* >>>>>>>> Utility routines used by other functions <<<<<<<<<<<<<< tf 


set_clip(r) ft set clip to specified rectangle tf 
BRECT tr j 

int pointsC43; 

grect_conv (r , points); 

vs_cl ip (handle, TRUE, points); 

> 


overlap (rl, r2) ft compute overlap of two rectangles tf 

BRECT tr I, tr2; 

C 

int x, y; 

x = MAX(r2->g__x, rl->g_x); 
y = MAX(r2->g_y, rl->g_y> j 

r2->g_w « MIN(r2->g_x + r2->g_w, rl->g_x + rl->g_w) -x ; 
r2->g_h = MIN(r2->g_y + r2->g_h, rl->g_y ♦ rl->g_h) -y; 
r2->g_x = x; 
r2->g_y o yj 

return ( (r2->g w > 0) StSc <r2->g h > 0> ); 

> 


redraw_msg (wh, r) ft Send Redraw Message to your own window tf 
int wh; 

BRECT tr ; 

< 

i nt ensg C B 3 ; 

<nsgC03 = WM_REDRAW; 
msgCll = gl_apid; 
msgC23 = 0; 

<nsgC31 n wh; 
cnsgC43 =* r->g_x ; 
msgCSl = t — >g_y; 
msgC63 = r->g_w; 

<nsgC73 = r->g_h; 

appl write(gl apid, 16, &msg) ; 

> 



n 

n 
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Program 3-2 is an abbreviated version of the same pro- 
gram in machine language. 







U 

u 


Program 3-2. messages 


***************** ****** ********* ******** «« ****** ************ 
* * 

* MESSAGE . S Shows how to handle window messages * 

r * 

************************************************************ 


*** External references 

** Exports 

.xdef demo * external demo subroutine, 

•xdef wdwctrl 

•xdef wdwtitl 

.xdef wdwinfo 

** Imparts 

.xref vdi 

. xref aes 

.xref contrl0 * all of the VDI data arrays 

.xref contrll 

•xref contrl2 

-xref contrl3 

.xref contrl4 

.xref contrlS 

.xref contrl6 

.xref intin 

.xref ptsin 

.xref ctrl0 * all of the AES data arrays 

.xref ctrll 

.xref ctrl2 

.xref Ctrl 3 

.xref ctrl4 

.xref aintin 

.xref aintout 

.xref addrin 

.xref deskx 

.xref desky 

.xref deskw 

•xref deskh 

.xref workx 

•xref worky 

.xref workw 

•xref workh 


.text 

demos 

move #0,d4 * close window flag in d4 

* create and open second window 

move #100,ctrl0 * command = wind_create 

move #3, ctrll * 5 input integers 

move #1, Ctrl 2 * 1 ouput integer 

move wdwctrl , aintin * window Ctrl flag 

move deskx , aintin+2 * max x 

move desky , aintin+4 * max y 

move deskw, aintin+6 * max width 

move deskh, aintin+8 * max height 
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move 

aintout, wh2 


* save window handle 

ttt set window 

name 



move 

#105,ctrl0 

* 

command =* wind_set 

move 

#5, ctrl 1 

t 

5 input integers 

move 

wh2, aintin 

* 

window handle 

move 

#2, aintin+2 


* subcommand = set window name 

move. 1 

#titl 2, aintin+4 * point to title 

jsr 

aes 




n 

n 

n 


Mt Open the window 

move #101 , ctrl0 * command « wind_open 
move #5, Ctrl 1 

move #1, Ctrl 2 * 1 output integers 

move deskw, d0 

asr #2,d0 

add deskx,d0 

move d0,aintin+2 * initial x =* deskw/4 + deskx 

move deskh,d0 

asr #2,d0 

add desky, d0 

move d0, aintin+4 * initial y - deskh/4 + desky 

move deskw, d0 

asr #l,d0 

move d0,aintin+6 * initial width =* deskw/2 

move deakh,d0 

asr #l,d0 

move d0,aintin+8 * initial height = deskh/2 

jsr aes 


mains 


move 

#23, ctr 10 

* 

opcode = evnt_messag 

move 

#0, Ctrl 1 



move 

#1 ,ctrl2 

t 

1 intout 

move 

#1 , ctr 1 3 

* 

1 addrin 

move 

#0, ctr 1 4 



move. 1 

#msg,addrin 



Jsr 

aes 



move 

#0, ctrl 3 



jsr 

msghand 

* 

handle the message 

crnpi 

#0,d4 

* 

check if window close 

beq 

main 

* 

if not, keep going 


t delete window 2 

move #103, ctr 1 0 * command = wind_delete 

move #1, ctr 11 

move #1, ctr 12 

move wh2,aintin 

jmp aes 

it >>>>>>>>>> End of Main Program Code <<<<<<<<<<<<<<<< *i 

*** Message handler subroutine *** **** 
msghand: 

move msg,d5 t check message type 

crnpi #27, d5 * WM.SIZED? 

bgt msg5 * if greater, skip 

bne msg2 


n 

n 

n 

n 

n 
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msgl i 

move #105, Ctrl 0 t command = wind.set 

move #6, Ctrl 1 * 6 input integers 

move msg+6, aintin * window handle 

move #5,aintin+2 t subcommand = set current size 

move msg+8, aintin+4 

move msg+10, aintin+6 

move msg+12, aintin+B 

move msg+14,aintin+10 

jmp aes 

msg2: 

cmpi #22, dS * WM.CLOSED? 

bne msg3 

* Close the Window 

move #102,ctrl0 t command = wind .close 

move #l,ctrll 

move #l,ctrl2 

move #0, ctr 13 

move #0, ctrl 4 

move wh2, aintin 

move #l,d4 

jmp aes 

msg3x 

cmpi #21, d5 « WM.TCPPED? 

bne msg4 

move #105, Ctrl 0 * command = wind.oet 

move #6, ctrl 1 t 6 input integers 

move msg+6, aintin t window handle 

move #10,aintin+2 * subcommand = WF.TOP 

jmp aes 

msg4i 

cmpi #20, d5 t WM.REDRAW? 

bne cnsgS 

jsr refresh 

ensgS* 

rts 

ttt Window refresh subroutine ttt 
refresh* 

t turn mouse off 

move #78,ctrl0 * command = graf .mouse 

move #l,ctrll * 1 input integers 

move #1, ctrl 2 It 1 output integer 

move #256, aintin t hide the mouse 

jsr aes 

* lock scren 


U 

u 


move #107, ctrl0 t command » wind.update 

move #1 ,ctrl 1 * 1 input integers 

move #1, ctrl 2 * 1 output integer 

move #1, aintin * code = BEB.UPDATE 

jsr aes 
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* Find first 

window rectangle 

! 1 

n 

move 

#104, ctrl 0 * 

command = wind_get ' 

move 

#2, Ctrl 1 * 

2 input integers 

move 

move 

#5, Ctrl 2 * 

msg+6, aintin 

5 ouput integers 

* window handle j j 

* WF.FIRSTxYWH command | | 

move 

#1 1 , ainti n+2 

jsr 

ao3 


ref reshl j 

* check for empty rectangle 

move 

aintout+6,d0 

or 

aintout +8,d0 

beq 

ref resh3 

$ if empty, at end, so quit 

move 

msg+8,d0 


move 

aintout +2, dl 


cmp 

d0,dl 

* x ■ MAX (xl, x2) 

bcs 

ol apl 


move 

dl,d0 

t overlap x is in d0 

olapl : 



move 

msg+10,dl 


move 

aintout+4,d2 


cmp 

dl,d2 


bcs 

olap2 


move 

d2,dl 

* overlap y is in dl 

ol ap2: 



move 

msg+8,d2 


add 

msg+12, d2 


move 

aintout +2, d3 


add 

aintout +6, d3 


cmp 

d2, d3 


bhi 

ol ap3 


move 

d3, d2 

* d2 a MIN (x 1+wl , x2+w2) 

ol ap3: 



sub 

d0,d2 


move 

d2, aintout+6 

t overlap w = d2 - overlap x 

move 

msg+10,d2 

* d2 = yl 

add 

msg+14,d2 

* + hi 

move 

ai ntout+4, d3 

t d3 a y2 

add 

aintout+8, d3 

* + h2 

cmp 

d2,d3 


bhi 

ol ap4 


move 

d3,d2 

* d2 = MIN <y 1+hl , y2+h2) 

olap4: 

sub 

dl,d2 

n 

move 

d2, aintout+8 

* overlap h = d2 - overlap y 

or 

ai ntout+6, d2 

% are width and height both 0? I" ""i 

* if so, skip redraw and get next rect 

beq 

ref resh2 

t set clip rectangle 


move 

# 12V. contr 1 0 

* opcode for set clip (vs_cl ip) P*~"] 

* two points in ptsin | | 

move 

#2, contrl 1 

move 

#0, contr 1 2 

move 

# 1 , contr 1 3 


move 

#0, contr!4 


move 

41 , i n tin 

* turn clipping on 
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d0,ptsin 
aintout+6, d0 
4)1, d0 
d0, ptsin+4 
dj f ptsin+2 
ai ntout+B,dl 
4)1, dl 

dt,ptsin+6 


* pointetfll = overlap x 

* points £2 3 = overlap x+w -1 

* pointed! » overlap y 

* pointsCSl = overlap y+h -1 


* redraw the display 

jsr display 

* turn clipping off 


4)129, contrl G 
412, contrl 1 
410, contrl 2 
4)1 , contrl 3 
#0, contrl4 
4)0, intin 


* opcode for set clip <vs_clip) 
$ two points in ptsin 


$ turn clipping off 


$ get next window rectangle 


ref resh2i 
move 
move 
move 
move 
move 


t unlock screen 


4)104, Ctrl 0 * command = wind_get 

4)2, Ctrl 1 * 2 input integers 

4)5,ctrl2 t S ouput integers 

msg+6,aintin * window handle 
4)12, aintin+2 * WF_NEx TxYWH command 

aes 

ref reshl 


ref resh3i 


move 

4)107, ctrl0 

* 

command = wind_update 

move 

4)1 , Ctrl 1 

t 

1 input integers 

move 

#1 , ctrl2 

* 

1 output integer 

move 

Jsr 

4)0, aintin 
aes 

t 

code * END_UPDATE 

mouse on 

move 

4)7B,ctrl0 

t 

command =* graf_mouse 

move 

#1 , Ctrl 1 

t 

1 input integers 

move 

#1 , ctrl2 

) 

1 output integer 

move 

4)237, aintin 

* 

hide the mouse 


t*t Window display subroutine ttt 
display) 

* Find window work area size 


4104, ctr 1 0 * command = wind_get 

4)2, Ctrl 1 S 2 input integers 

#5, Ctrl 2 t 5 ouput integers 

msg+6, aintin 

#4, aintin+2 t WF.WORKXYWH command 
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Jsr aes 

move aintout+2, work* t store work x,y,w,h 

move aintout+4, worky 

move ai ntout+6 , wo r kw 

move aintout+8,workh 

* set fill pattern to hollow 


move 

923, contr 10 

* 

move 

40, contr 1 1 


move 

40, contr 12 


move 

91, contr 13 

i 

move 

41,contrl4 


move 

40, intin 

i 

Jsr 

vdi 



opcode for set fill type 

one integer in intin 
select hollow fill type 


t*t Storage space and data constants 
• data 
. even 

msgs •ds.w 8 

wdwtitl: .dc.b * First Window", 0 

titl2: .dc.b 'Second Window" ,0 

wdwinfo: .dc.b ",0 

wdwctrl : . dc.w 33 

wh2: .ds.w 

. end 


Scroll Bars and Their Messages 

When you want to display more information than you can fit 
onscreen at one time, you may wish to make the window a 
view port onto a larger area. By using slide bars (or scroll bars), 
you allow the user to select which portion of the window's con- 
tents to view. As with the other GEM features discussed here, 
actually scrolling the document is the responsibility of your 
program, but GEM helps out by providing a standard frame- 
work within which scrolling may be implemented. 

The standard GEM scroll bar consists of three elements: a 
movable bar called a slider, a long rectangular box the slider 
moves within, and arrow characters at either end of the rec- 
tangular box. These elements can be added to the window by 
specifying the elements LFARROW, HSLIDE, RTARROW 
and/or the elements UPARROW, VSLIDE, DNARROW as part 
of the window controls flag used by wind_create( ). 

When a window contains all three elements (for instance, 
the LFARROW, HSLIDE, and the RTARROW), the user can 
take three types of action. First, the user can drag the slider by 
positioning the mouse pointer over it, holding the left button 
down, and moving the mouse. Second, the user can click on 
either arrow, indicating that the contents of the window are to 
be moved a character at a time. Or, third, the user can click on 
the scroll bar between the slider and the arrow, indicating that 
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the contents of the window are to be moved a page at a time. 
All of these events generate window messages. These mes- 
sages will be discussed in detail below. 

In order to maintain slider bars in a GEM application, you 
must perform three tasks. 

Slider size. First, you must keep track of the slider size. 
The portion of the scroll bar that's filled by the slider bar is 
supposed to represent the percentage of the total display area 
shown on screen. If half of the total display area is shown 
onscreen at a time, the slider bar should fill half the scroll bar. 
The AES allows you to set the size of the bar with a value in 
the range 1-1000. Each unit corresponds to one tenth of 1 per- 
cent of the total size of the scroll bar. A bar size of 1 fills the 
minimum possible area, while a bar size of 1000 fills the en- 
tire slide box. If the length of the part of the display that's 
seen is less than the total length available for display, you can 
calculate the size of the slider with the formula: 

size = 1000 * (length_seen/total_ length) 

If you use this formula, you must be careful to check that 
the length seen is less than the total length, however, or you'll 
come up with a number larger than 1000. Also, you should 
probably use 32-bit variables for the computation to avoid ex- 
ceeding the size limit of 16-bit integers. In C, these are vari- 
ables that are declared to be of the type long. After you've 
computed the relative size of the slider, you can set the bar to 
this size using the WF—VSLSIZE or WF—HSLSIZE windset( ) 
function: 

wind_set(wi_handle, WF_VSLSIZE, size, 0, 0, 0); 
wind_set(wi_ handle, WF_HSLSIZE, size, 0, 0, 0); 

Your program should adjust the size of the slider if either 
the window or the document changes size. If the size of the 
window changes, you'll know because you will have received 
the WM—SIZED message and will have sized the window with 
wind— set( ). 

When the size of the document changes, because the user 
deleted a line of text, for example, you should update the 
slider size only if the change alters the proportions significant- 
ly. After calculating the new size, check it against the current 
size. You can find the current slider size by using the 
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WF—HSLSIZE and WF—VSLSIZE subcommands of ivind—get(): 

wind_get(wi handle, WF—VSLSIZE, &size, &dummy, &dummy, 

&dummy); 

wind_get(wi_handle, WF—HSLSIZE, &size, &dummy, &dummy, 
&dummy); 

where size is the variable in which the current size is returned, 
and dummy is a dummy place-holder variable which must be 
used because wind_get( ) returns four values. If the new size 
is equal to the old size, you needn't update it. 

Slider position. The second part of the task of maintain- 
ing scroll bars is keeping track of the slider position. 

As with slider size, the slider position setting has a range 
of 1-1000. But this setting is tricky. It doesn't reflect the abso- 
lute position of the slider within the scroll bar. Instead, it 
marks the position of the top of the slider bar relative to its 
possible range of positions. Since the slider itself can take up a 
significant portion of the scroll bar, the top of the bar usually 
can't go down to the bottom of the scroll bar. For example, if 
the window display shows 20 lines of a 200-line text document, 
the vertical slider fills 10 percent of the area of the scroll bar. 
That means the top of the slider can never go down more than 
90 percent of the way. The other 10 percent is taken up by the 
bar. In that situation, position 1000, the bottommost position 
on the bar, is 90 percent of the way down the scroll bar. 

If the window displays 20 lines of a 100-line document, 
the slider occupies 20 percent of the area of the scroll bar. In 
that case, position 1000, the farthest that the top of the slider 
can go, is only 80 percent of the way down the scroll bar. 
Therefore, you must calculate the position of the top of the 
slider as a fraction of the total available range of motion. For 
example, in the case of the 200-line document, 20 of which 
are displayed, the total range is 200 — 20, or 180 lines. If line 
39 is displayed in the top of the window, the bar should be 
placed at position (1000 * 39 / 180), or 216. This position set- 
ting is a little larger than the setting of 200 you'd intuitively 
guess to be the correct setting when the top of the display 
shows the line that's 20 percent of the way down the docu- 
ment. The larger the slide bar gets, the larger this discrepancy 
grows. For example, if you make the document half as long. 
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you'd expect the setting to double. But if the window shows 
20 lines of a 100-line document, and the top of the window 
shows line 39, the correct position setting is (1000 * 39 / 80), 
or 487, which is significantly more than double the earlier set- 
ting of 216. Where the portion of the display shown in the 
window is less than the total amount available for display, you 
can calculate the slider position with this formula: 

position = 1000 * window-start / (total— length — length— seen) 

where windowstart represents the position that's displayed at 
the beginning of the window. For example, if line 40 of a doc- 
ument were displayed at the top of the window, window— start 
would be 39, because it's conventional to start counting the 
display position at 0. That way, if you're at the top of the doc- 
ument, the slider position is 0 (0 divided by any number is al- 
ways 0), rather than some small fractional position number. 
Remember also that if the length seen is equal to or greater 
than the total length (the slider size is 1000), you must always 
position the slider at 0. Once you've calculated the correct 
slider position, you position it with the WF_ HSLIDE or 
WF_ VSLIDE subcommand of wind_set( ): 

wind— set(wi_ handle, WF_ VSLIDE, position, 0, 0, 0,); 
wind— set(wi_ handle, WF_ HSLIDE, position, 0, 0, 0,); 

You'll know it's time to update the position of the slider 
when you get one of the window messages associated with the 
scroll bar. For example, when the horizontal slider is moved, 
message 25, WM_ HSLID is sent: 

Word 

Number Contents 

0 25 (WM— HSLID), the message ID number 

3 The handle of the window whose horizontal slider was 
dragged 

4 The requested position for the left edge of the slider (a 
number from 0 to 1000, where 0 = far left, 1000 = far 
right) 

The user, dragging the vertical slider, generates message 
26, WM-VSLID: 
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Word 

Number Contents 

0 26 (WM—VSLID), the message ID number 

3 The handle of the window whose vertical slider was 
dragged 

4 The requested position for the top edge of the slider (a 
number from 0 to 1000, where 0 = top, 1000 = bottom) 

Since the number returned in msgbuf[4] is in the proper 
format, you may want to pass the new setting on to 
wind_set( ) unchanged: 

wind_set(msgbuf[3], WF-VSLIDE, msgbuf[4], 0, 0, 0); 

If the display is comprised of indivisible logical units, 
however, you'll want to round the movement of the slider to 
the nearest such unit. If the window display shows lines of 
text, for example, you'll want to scroll the display by an even 
number of text characters. One easy way of rounding is to find 
the window start position that corresponds to slider position 
and convert that start position back to a slider position. How 
to calculate the window start position will be discussed under 
the section on refreshing the window display later in this 
chapter. 

When any of the other events associated with slide bars 
occurs, the Screen Manager sends message 24, WM_J\RROWED: 

Word 

Number Contents 

0 24 (WM_ ARROWED), the message ID number 

3 The handle of the window whose scroll bar was clicked 

4 The action requested by the user: 

0 Page up (user clicked on scroll bar above vertical 
slider) 

1 Page down (user clicked on scroll bar below vertical 
slider) 

2 Line up (user clicked on up arrow) 

3 Line down (user clicked on down arrow) 

4 Page left (user clicked on scroll bar left of horizontal 
slider) 

5 Page right (user clicked on scroll bar right of horizon- 
tal slider) 

6 Column left (user clicked on left arrow) 

7 Column right (user clicked on right arrow) 


n 

n 

n 

□ 

n 


n 

n 

n 

n 
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As you can see, the eight possible cases are represented as 
subcommands in msgbuf[4], What exactly your program does 
in response to these messages depends somewhat on the type 
of information being displayed. By convention, when the user 
clicks on an arrow, the display should scroll by the smallest 
indivisible unit. If the display is text, for example, you incre- 
ment or decrement the starting position of the display by one 
character row or column and move the slider accordingly. 
When the user clicks on the scroll bar between an arrow and 
the slider, you should scroll the display by a larger increment, 
typically the number of units that fit on a display screen. Thus, if 
20 lines of text fit on a screen, you might scroll the document 
by 20 lines. Check first to make sure that you're more than 20 
lines from the beginning or end of the document. 

In addition to window messages, your program should be 
ready to adjust the slider position in response to changes in 
the window size or document size. As with the slider size, 
however, before you make any change in the position of the 
slider, you should first check to make sure that the new posi- 
tion will actually be different than the current one. You can 
determine the current slider position with the WF—HSLIDE 
and WF—VSLIDE subcommands of wind get( ): 

wind_get(wi_handle, WF—VSLIDE, deposition, dedummy, 
dedummy, dedummy); 

wind— get(wi_handle, WF—HSLIDE, deposition, dedummy, 
dedummy, dedummy); 

where position is the variable in which the current position is 
returned, and dummy is a dummy place-holder variable which 
must be used because wind— get( ) always returns exactly four 
values. If the new position is equal to the old one, you needn't 
perform the update. 

Updating the window display. The third and final part 
of maintaining a window that contains scroll bars is updating 
the window display. You will not get a window redraw mes- 
sage when you use wind— set to change the size or position of 
the slider. You must take the initiative either to call your re- 
draw routine directly, or to send yourself a redraw message. In 
order to calculate where in the document to start the window 
display, you may have to do the reverse of the calculation that 
you did to find the slider position from the document start: 

window_start = slider_position*(tota] length — length seen) /1000 
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Again, window-start counts the top of the document as 0, 
and you'll probably want to use 32-bit variables in order to avoid 
exceeding die limits of 16-bit arithmetic. Once you have the 
window-start position, you'll want to save it. That way, if the 
user clicks on one of the arrows, you can simply increment or 
decrement it by 1 and redraw, and if the window size changes, 
you can begin the window in the same place. 

Program 3-3 shows how to handle the messages associ- 
ated with maintaining the scroll bar. 

Program 3-3. scroll.c 

/MM**************************************************************/ 


/* */ 

/* SCROLL.C — Demonstrates how to manage scroll bars */ 

/* in a window. */ 

/* */ 

/* */ 


/«**** *************************************************** **********/ 

tidefine FALSE 0 
tidefine TRUE 1 
tide-fine APP_INFO ,,M 

tidefine APP_NAME "Scroll Window Example" 

•define WDW.CTRLS (NAME I CLOSER ! VSLIDE 1UPARRCW I DNARROWl 
tidefine MAX<X,Y> < (X) > (Y) ? (X) * (Y) ) 

tidefine MIN(X,Y> < (X) < (Y) ? (X) s (Y> ) 

tidefine TROWS 28 /* total number of text row */ 

tidefine TCOLS 30 /* total number of text columns */ 

tidefine SROWS 9 /* number of rows seen at a time */ 

•include "aesshel 1 .c" 

int msgCSl; /* message buffer */ 

int ttop; /* the top line of text currently in the window */ 

char *text CTRQWS1 = 
f 

"This is a sample help window. ", 

"The total text is too large to**, 

"be displayed on screen at one ", 

"time. In order to see the rest", 

"of the text, you must use the ", 

"right scroll bar. ", 

" f 

"There are three different ways", 

"you can scroll the text. The ”, 

"first is to click on the up or", 

"down arrows. This scrolls the", 

"text up or down, one line. ", 

"Of course, if the first line ", 

"of text is already at the top,", 

"you can't scroll up. Nor can ", 

"you scroll down if you’re at ", 

"the botton of the window. ", 

II II 

9 

"The second way to scroll is to", 

"click on the space between the", 

"slider and the arrow. This ", 

"moves the text up or down a ", 

"page at a time. ", 



□ 

n 



n 
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"The third way is to drag the M , 

"slider with the mouse. This M , 

"moves the text a proportional ", 

"distance up or down. ", 

>5 

demo ( ) 

int done) /% close window flag */ 

long slsizei /* size of slider */ 

vst.al ignment (handle, 0, 5, fcdone, &done); /* set text alignment */ 
ttop = 0) /* start with top line of text at top of window tf 

/* calculate exterior size of window for text */ 

wind_calc(0, WDW.CTRLS, 

cellw * 5, cel lh * 5, cellw * TCDLS+4, cellh * SROWS+4, 
&work.g_x, &work.g_y, &work.g_w, S«work.g_h); 

/* set the window to that size */ 

wind_set(wi_handle, WF_CURRXYWH, 

work.g_x, work.g_y, work.g_w, work.g.h); 

/* find slider size and set it */ 

slsize o (1000 * SROWS) / TROWS; 

wind_set(wi .handle, WF.VSLSIZE, (int)slsize, 0, 0, 0) | 


wind.get (wi. handle, WF.WORKXYWH, Scwork.g.x, fcwork.g.y, 


fcwork.g.w, 8<work.g_h>; 

ft find work area tf 

do 

( 

ft 

main program loop */ 

evnt.mesag (msg ) ; 

ft 

get message ... tf 

done 1=1 handle.msg ( ) ; 

j 

/% 

and handle them ... : 

whi le ( ‘done) ; 

ft 

til window is closed 







> 

handle msg() /* message handler %/ 

<. 

int done “ FALSE; 
long temp; 

switch (msgC03) 

( 

case WM.REDRAW: 
ref resh (msg C33 , 
break; 

case WM TOPPED: /* if topped, send to top t/ 

wi nd_set ( msg C 3 3 , WF_TOP, 0, 0, 0, 0); 
break; 

case WM_CLOSED: ft if closed, set flag tf 

done'o TRUE; 
break; 

case WM.VSLID: / * slide bar was dragged */ 

temp”= msg C4 3 * (TROWS-SROWS) / 1000; /* calc ttop */ 
ttop - temp; 

ref resh (wi _handl e, Scwork); /% redraw window */ 
move.sl ide < ) ; /* and move slider */ 

break; 


ft check message type */ 

/* if redraw, call refresh routine */ 
(GREET * ) &msgC43 ) ; 
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case WM_ ARROWED: /* arrow was clicked */ 

switch ( cnsg C 4 1 ) 

< 


case 0: /tpage up*/ 

ttop = MAX <0, ttop -SROWS) ; 
break; 

case 1: /tpage down*/ 

ttop a M I N ( TROWS— SROWS , ttop+SROWS) ; 
break; 

case 2: /* row up */ 

ttop = MAX (0, ttop-1); 
break; 

case 3: ft row down */ 

ttop = M I N < TROWS -SROWS , ttop+1); 
break; 

default: 

break; 


refresh(wi_handle, &work) ; /* redraw window */ 

move_slide< ) ; /* move the slider */ 

break; 


def ault: 
break; 

> 

return (done) ; 

> 


refresh(wh, drect) 
int wh; 

BRECT tdrect; 

< 

BRECT wrect; 


/* routine to handle window_ref resh <WM_REDRAW) */ 
/* window handle from msgC33 */ 

/* pointer to damage rectangle */ 

/* the current window rectangle in rect list */ 


graf _mouse(M_GFF, 0L); ft turn off mouse */ 

wi nd "update <BEG_UPD ATE) ; /* lock screen */ 


n 

n 

n 

n 

n 


wind_get /* get first rectangle */ 

(wh, WF_FIRSTXYWH, &wrect.g_x, *twrect.g_y, &wrect.g_w, & wrect . g_h> ; 


while ( wrect. g w Stic wrect.g_h ) 
€ 

if (overlap (drect, fewrect)) 

C 

set_cl i p (Stwrect ) ; 
display () ; 

vs_clip (handle, FALSE, 


/* while not at last rectangle, */ 

/* check to see if this one's damaged, 

/* if it is, set clip rectangle */ 
ft redraw, and turn clip off */ 

(int *>&wrect >; 


wind_get(wh, WF_NEXTXYWH, &wrect.g_x, Scwrect.g_y, 8twrect.g_w, 
Scwrect.g_h) ; 


> 


*/ 



wi nd_update (END_UPDATE) ; 
graf mouse(M_ON, 0x0L) ; 

> 


/* unlock screen */ 

/* turn mouse pointer back on */ 



displayO /* draw the window display */ 

< 

int x; 

/* print each visible line of text, starting with ttop */ 
for (x b 0; x < SROWS; x++> 

v^gtext (handle, work.g_x, cellh * x + work.g_y, text Cttop+x 3 > ; 

> 
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move.slldoO /* move the slider to match ttop */ 

C 

int cslide, nslide; 
long temp; 

wind get(wi handle, WF_VSLIDE, &cslide, &nslide, &nslide, fcnslide); 
temp = 1000 • ttop/ (TROWS-SROWS); 
if < <nsl ide=temp) != cslide) 

wind.set<wi .handle, WF.VSLIDE, nslide, 0, 0, 0)} 


/% »»»» Utility routines used by other functions <<<<<<<<<<<<<< */ 


Bet.clip(r) /• set clip to specified rectangle */ 
6RECT *r ; 

int pointst43; 

grect.convtr, points); 

vs.cl ip (handle, TRUE, points); 

> 


overlap (rl, r 2) /* compute overlap of two rectangles */ 

GRECT trl, *r2; 

{ 

int x, y, xl, yl; 

x =» MAX <r2— >g_x , rl->g_x>; 
y = MAX <r2->g_y, rl->g.y); 

r2- >g_w = MIN <r2->g.x + r2->g_w, rl->g_x + rl->g_w) -x; 
r2— >g_h = MIN<r2->g_y + r2->g_h, rl->g.y + rl->g_h) -y; 
r2->g_x = x; 
r2->g_y = y; 

return < <r2->g w > 0) Se?t (r2->g h > 0) ); 

> 



Notice that the window display was updated by printing 
each line of text, one after the other, using the V—gtext( ) rou- 
tine. This process is fairly quick, as long as you keep the text 
aligned on byte boundaries. When speed is important, how- 
ever, you'll want to update a scrolled display by moving the 
block whose contents remain valid with the VDI raster routine 
vro—cpyfm() and then filling in the new data. In some cases, 
you may even wish to keep an entire copy of the window's 
contents stored offscreen in a memory buffer area. Then, when 
you want to refresh the window, you only have to move the 
relevant portion of that information using vro_cpyfm( ). 
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Mouse Button Events 

The next type of event is the mouse button event. This func- 
tion does much more than merely wait for the user to push a 
button. It allows you to specify the particular combination of 
buttons you are waiting for, whether you want those buttons 
to be pressed or released, and the number of button clicks you 
want to wait for as well. To wait for a mouse button event, call 
evnt— button: 

int clicked, clicks, bmask, bstate, mousex, mousey, button, kstate; 

clicked = evnt_button(clicks, bmask, bstate, &mousex, 
&mousey, &button, &kstate); 

The input parameter clicks lets the AES know the maxi- 
mum number of button clicks you're waiting for. If you're in- 
terested in double-clicks as well as single clicks, enter the 
number 2 for clicks. If you're only interested in single clicks, 
make clicks equal to 1. When a button is first pressed, GEM 
starts timing a short interval. For each time that the button 
goes up and down again during that interval, it adds one click 
to its count. The actual number of clicks is returned in the 
variable clicked. GEM doesn't check the number of clicks, 
however, if you're waiting for more than one button. 

The length of time during which GEM counts clicks de- 
pends on the current double-click speed setting. This setting 
may be changed from the Control Panel desk accessory that 
comes with the ST to any of four settings. It's also possible to 
change this time interval from within a program, using the 
evnt—dclick( ) call: 

int speed— set, speed, flag; 
speed-set = evnt— ddick(speed, flag); 

where flag indicates whether you want to read the current 
double-click setting (flag is 0), or make a new setting (flag is 
not 0). If you wish to make a new setting, set the speed vari- 
able to a number in the range 0-4, where 0 specifies the long- 
est double-click interval, and 4, the shortest. The setting 
requested, either the current or new setting, is returned in the 
variable speed— set. Since the speed of the double-click setting 
may affect the speed with which mouse button events are re- 
turned, you may wish to change the speed before a mouse 
button event call and change it back afterwards. 
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In the evnt—button( ) call, the two input variables bmask 
and bstate are used to specify which buttons you want to wait 
for and whether you want to wait for them to go down or up. 
The bmask variable is the one you use to specify which but- 
tons to watch. Bit 0 of this word corresponds to the left mouse 
button, and bit 1, to the right mouse button. If you want to 
watch the left button, set bmask to 1. If you want to watch the 
right button you set it to 2. If you want to watch both, set it to 
3. The bstate variable is used to specify whether you want to 
wait for the buttons to go down or up. You set the appropriate 
bit to 0 if you want to wait for the button to be released, or 1 
if you want to wait for it to be pressed. 

The mouse button event will only occur when the condi- 
tions specified in bstate for the buttons specified in bmask 
happen at the same time. This means that you can wait for the 
left button or the right button to go up or down, or you can 
wait for both. You cannot, however, wait for either the left or 
right button to change state. This makes its impossible for a 
program to watch for more than one mouse button condition 
using the standard event-driven input scheme. In order to use 
both buttons, you will have to return to the polling type of in- 
put discussed at the beginning of this chapter. A polling tech- 
nique will be discussed under the section on the evnt—multi( ) 
call below. 

The actual mouse button state at the end of the double- 
click interval is returned in the button variable. As with the 
bstate variable, the value is 1 if the left button is down, 2 if the 
right button is down, or 3 if both are down. By checking the 
mouse button status, the program can determine whether the 
user merely clicked the button or is holding it down. In addi- 
tion to the mouse button status, the Shift key status is also re- 
ported. The kstate variable contains a code that tells whether 
the right Shift key, the left Shift key. Control key, or Alt key 
was pressed at the same time as the mouse button. Each of the 
four low bits represents a different key: 

Bit 

Bit Value Key 

0 1 Right Shift 

1 2 Left Shift 

2 4 Control 

3 8 Alt 
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Thus if kstate contains a 4, the Control key was held 
down when the mouse button was pressed, and if it has a 
value of 12, both Alt and Control were held. The final two 
values that evnt— button returns are the coordinates of the 
mouse pointer at the time the button was pressed. Its horizon- 
tal position is returned in mousex, and the vertical position in 
mousey. 

As of this writing, there's a serious bug in the 
evnt_button( ) routine in the TOS ROMs. If the mouse pointer 
is moved into the menu bar while your program is waiting for 
a mouse button event, the machine will lock up. The problem 
would also occur under similar circumstances if you use the 
evnt—multi( ) call to await a mouse button event. There's no 
way to avoid this problem except to use polling techniques 
(described below) rather than waiting for mouse button events. 


Mouse Rectangle Events 

When the AES waits for a mouse rectangle event, it watches 
the mouse pointer's position and informs you when the 
pointer enters or leaves a designated area on the screen. This 
elegant system eliminates the need for your program to keep 
checking the mouse pointer's position. To wait for a mouse 
rectangle event, you call evnt—mouse( ), in the following 
format: 

int reserved, mflag, rectx, recty, rectw, recth, 
mousex, mousey, button, kstate; 

reserved == evnt_mouse (mflag, rectx, recty, rectw, recth, 
&mousex, &mousey, &button, &kstate); 

where the mflag input variable is used to indicate whether you 
want to watch for the pointer entering the area or leaving it. A 
value of 0 means that you want to watch for its entry, and a 
value of 1 means that you want to watch for its exit. The x po- 
sition, y position, width, and height of the rectangle are passed 
in the variables rectx, recty, rectw, and recth. 

As with mouse button events, the status of the mouse 
buttons is returned in the variable button, and the status of the 
shift keys in the variable kstate. The meaning of these coded 
returns is the same as for the mouse button events, above. 
GEM reserves a return variable for future use. Currently, a 
value of 1 is always returned in reserved. 
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Mouse rectangle events have many uses. A common one 
is to notify the program when the mouse enters a particular 
area of the screen so the program can change the mouse 
pointer form. Rectangle events can also be used to detect any 
movement of the mouse. Simply wait for the pointer to exit 
from a rectangle one pixel in size and located at the current 
pointer position 

Keyboard Events 

You can wait for the user to press a key on the keyboard by 
calling the function evnt_keybd( ). The syntax for this function 
is 

int keycode; 

keycode = evnt_keybd( ); 

where the variable keycode contains a two-byte value that 
specifies the key or combination of keys struck and the ASCII 
value of that combination. The first byte usually identifies the 
key that was struck and isn't affected by shift key combina- 
tions. The second byte is the ASCII value of the key combina- 
tion, which does depend on the state of the shift keys (Shift, 
Control, and Alt). In most cases, the ASCII value in the low 
byte is what the program is really looking for, and the high 
byte can be ignored. Keys which have no ASCII value, how- 
ever, such as the function keys, return a 0 in the low byte and 
must be read by the high byte alone. The entire list of 
keycodes may be found in Appendix B. 

Timer Events 

You may use the timer event to wait for a specified period of 
time. The format for the evnt—timer( ) call is 

int reserved; 

unsigned int timelo, timehi, 

reserved = evnt__timer(timelo, timehi); 

where timelo and timehi are the low word and high word of an 
unsigned 32-bit time period, expressed in milliseconds. This is 
the opposite of the order the 68000 uses to store a long word, 
so you'll have to split the 32-bit value into two halves before 
passing it to this function. In theory, the range of values avail- 
able allow you to time a period from one millisecond to 65.5 
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seconds with this function. In practice, however, you'll find 
that the ST's internal clock does not have sufficient resolution 
to time an event more closely than to the nearest five or six 
milliseconds. 

A timer event can be used to pace the action of your pro- 
gram or to provide a limit on the amount of time that your 
program will wait for a particular action. If you specify a time 
count of 0, the function returns immediately. This "do-nothing" 
event can be used periodically in your program, if no other 
AES calls are made, to maintain Screen Manager function. As 
stated in Chapter 1, the multitasking kernel can only switch 
tasks when the current one makes an AES call. 





Multiple Events 

Although each of the event calls was explained separately, 
there's a way to wait for any or all of these events at once. 
The evnt—multi( ) call lets you wait for a timer event, keyboard 
event, message event, mouse button event, and up to two 
mouse rectangle events, all at the same time. The format for 
this call is 

happened = evnt_multi(events, clicks, bmask, bstate, mlflag, 
mlrectx, mlrecty, mlrectw, mlrecth, m2flag, m2rectx, m2recty, 
m2rectw, m2recth, msgbuf, timelo, timehi, &mousex, &mousey, 
&button, &kstate, &keycode, ^clicked); 

Most of these input parameters and output parameters 
should be familiar from the explanations of the individual 
event calls. Only the variables events and happened are new. 
These are flags which indicate which events you asked to wait 
for and which events actually occurred. Possible flag values 


include: 



Bit 

Bit 

Value 

Macro Name 

Event 

0 

1 

MU—KEYBD 

Keyboard 

1 

2 

MU_BUTTON 

Mouse button 

2 

4 

MU—Ml 

Mouse rectangle #1 

3 

8 

MU—M2 

Mouse rectangle #2 

4 

16 

MU-MESAG 

Message 

5 

32 

MU-TIMER 

Timer 
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U 

u 

u 


u 

u 

u 

u 

u 


These can be joined in any combination. For example, a 
value of 19 in the events flag means that you want the AES 
to wait for message, mouse button, and keyboard events 
(16 + 2 + 1). Likewise, the flag for the actual events that oc- 
curred is returned in the variable happened. Since more than 
one event can happen at the same time, it's necessary to ex- 
amine each significant bit of the variable to find all of the 
events. 

The other variables retain the same meanings they had 
when used in individual event calls. Clicks, bmask, clicked and 
bstate are used for mouse button events. The variables that 
start with ml are for the first set of mouse rectangle events, 
and the ones that start with m2 are for the second set of 
mouse rectangle events. Msgbuf is used for message events, 
keycode for keyboard events, and timelo and timehi for timer 
events. Although mousex, mousey, button, and kstate are usually 
associated with mouse button or mouse rectangle events, the 
values returned in these variables are valid at the conclusion 
of any evnt—multi( ) call, regardless of whether or not a mouse 
button or mouse rectangle event occurred. 

The GEM literature suggests that you should always use 
evnt_multi( ) instead of the individual event calls. First, a 
well-written program usually allows for more than one kind of 
input from the user. Second, evnt_multi( ) allows you to use 
the timer in conjunction with other events. This makes it pos- 
sible to set a time limit on waiting, so that if the user doesn't 
respond within some reasonable time, your program can re- 
cover and help him out, rather than wait forever. 

There is a penalty for using evnt_multi( ) from C, how- 
ever. Because of the large number of input parameters, it takes 
time to push them all on the stack for the library function, and 
then it takes the library function time to pull them from the 
stack, place them in the proper data arrays, make the call, and 
move the values that were returned from the data arrays back 
to the output variables. 

Since the library routine in the bindings has to be pre- 
pared for the unlikely case that you'll want all of the events 
checked at the same time, you must always supply some value 
for all of the input parameters, whether you use them or not, 
and the bindings must move all of those values whether 
they're used or not. As a result, evnt_multi( ) can be sluggish, 
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particularly when you're closely tracking mouse movement, 
for instance. 

When your application requires faster performance, it may 
be beneficial to skip the library routines and write your own 
machine language interface that moves the necessary values to 
the int—in and addr—in data arrays before giving the TRAP 
command that calls the AES. 

Polling. As mentioned in the section on mouse button 
events, in order to use both mouse buttons in a program, you 
must poll the buttons rather than waiting for button events. 
You've seen that a timer event of duration 0 returns immedi- 
ately. So to continuously check the status of the mouse but- 
tons, all you have to do is keep calling evnt_multi( ) in a loop, 
looking for a timer event of 0. The values for button, kstate, 
and mousex, and mousey will be updated during each call. 
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The concept of gem graphics objects is the key 

to the GEM interface. These objects may be displayed onscreen as 
plain boxes, boxes with text in them, bit-images, icons, or editable 
text strings. Anyone who has used the ST is familiar with these 
objects. For example, the drop-down menus used by GEM pro- 
grams are composed of GEM objects. The menu bar, the menu ti- 
des, and each menu item is a separate GEM object. Each 
component in a dialog box or an alert box, such as the OK button, 
which is clicked at the end of an operation, is a GEM graphics ob- 
ject. The icons that appear in the Desktop program, representing 
disk drives, files, and folders, are all GEM objects. Even the con- 
trol components in a window, such as the dose box, the size box, 
and move bar are all GEM objects. Simply put, GEM objects are 
the basic building blocks for all of the sophisticated GEM visual 
constructs, such as dialog boxes and menus. 

At the programming level, these objects are data struc- 
tures that describe the composition and status of the figures 
seen on the screen. Most definitions concerning objects can be 
found in the OBDEFS.H header file. The C definition for an 
object data structure looks like this: 


typedef struct object 

{ 



int 

ob__next; 

/* object number of next "sibling" */ 


int 

ob_ head; 

/* object number of first "child" */ 


int 

ob— tail; 

/* object number of last "child" */ 

unsigned 

int 

ob—type; 

/* type of object— BOX, CHAR,... */ 

unsigned 

int 

ob— flags; 

/* flags for color, fill pattern...*/ 

unsigned 

int 

ob__state; 

/* flags for how to draw— SELECTED, 
and so on.*/ 


char 

*ob_spec; 

/* ADDRESS of object-specific info */ 


int 

ob_x; 

/* left edge of object */ 


int 

ob_y; 

/* top edge of object */ 


int 

ob_ width; 

/* width of object */ 

OBJECT; 

int 

ob— height; 

/* height of object */ 


Since objects are so important to GEM, and since the compo- 
sition of object data structures is somewhat complex, each 
member of the data structure will be explained in detail below. 
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Object Tree Structure 

While the concept of individual objects is a powerful one, the 
way GEM combines objects makes them even more powerful. 
A menu bar, for example, is made up of a number of individ- 
ual menu title objects and menu item objects. But in order for 
these objects to function together to make up a menu, it's nec- 
essary to define a relationship between them. The first three 
fields in the data structure for each object are used as pointers 
to other objects. These pointers, ob—next, ob—head, and ob—tail, 
define the relationship between objects, and make it possible, 
for example, to draw a series of related objects with a single 
command. 

The system used to link objects is called a binary tree. If 
you look at a diagram of such a tree, you'll notice that it re- 
sembles a family tree. A family tree starts with the earliest 
known common ancestor at the top, and shows each genera- 
tion branching out downward, so that the tree grows larger 
and larger the farther down you go. A binary tree works much 
the same way, and even uses the same terminology, so that 
parent objects may spawn groups of related objects, which are 
referred to as their children. 

A struct is a data structure as used in the C programming 
language. Structs might be formed of any kind of data. The 
type of struct is determined by the data it contains. Thus, if 
the struct contains object data, it is a struct of the object type. 
An object tree is simply an array of object structs. 

The object number of an object is the array index number 
of that object. The root object (object number 6) sits at the top 
of each object tree. The screen display rectangle of the root 
object completely encloses all of the other objects in the tree. 
The largest objects within the root are the sibling objects 
which are all children of the root object. Each of these objects 
may contain their own, smaller child objects. 

The root object, like all other objects, contains three link- 
age fields at the beginning of its data structure. These fields 
are called ob—next, ob—head, and ob—tail. The NEXT field con- 
tains the object number of the next object which is a child of 
the same parent as the current object (such objects are known 
as siblings). Since the root object by definition has no parent, it 
can have no siblings. Therefore, its NEXT field contains a —1, 
which means that there's no link in this direction. For objects 
which do have siblings, the NEXT field of each contains the 
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object number of the next sibling. The last sibling at a particu- 
lar level contains the object number of the parent in its NEXT 
field. If an object has children (the root object nearly always 
has children), the HEAD link field contains the object number 
of the first child, and the TAIL field contains the object num- 
ber of the last child. 

To better understand how object trees work, it would be use- 
ful to examine one. Figure 4-1 shows a sample GEM dialog box. 
This box is made up of seven objects. The root object is the 
G—BOX that surrounds all of the other objects, which we'll call 
DIALBOX. Object 1, OKBUTTON, is the box labeled OK. Its sib- 
ling, Object 2, PATBOX, is the pattern-filled box that holds the 
rest of the objects. Its two children are Object 7, INSTRUCT (the 
SELECT.. .text box) and Object 3, a box named INVISBOX. Don't 
strain your eyes looking for INVISBOX — as it's name suggests, it's 
invisible. This box surrounds its three children, the box objects 
marked A, B, and C. These are Objects 4, 5, and 6, which we'll 
call BUTNA, BUTNB, and BUTNC, respectively. 


Figure 4-1. GEM Dialog Box and Its Contents 





Figure 4-2 illustrates the link fields for the seven objects. 
Object 0, the root, has no siblings in its NEXT field, but its 
HEAD field points to its first child, object 1, and its TAIL field 
points to its second (and last) child, object 2. Object 1 has no 
children, so HEAD and TAIL contain a —1, but it does have a 
sibling, so NEXT points to object 2. Since object 2 has no 
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more siblings, its NEXT field points back to object 0. Its HEAD 
field points to object 3, its first child, and its TAIL field points 
to object 7, its last child. 


Figure 4-2. Link Fields for Objects in Dialog Box 



If you look at the sample object tree, you may find the 
numbering of objects a bit odd, with objects 3 and 7 at one 
level, and objects 4, 5, and 6 at a lower level. This is the order 
in which these objects are written out by the Resource Con- 
struction program which we'll discuss in the next chapter, and 
it's indicative of the order used to walk the tree. Walking the 
tree is a process by which you start with the root object and 
visit each of the subordinate objects in turn. Using the link 
fields, you can examine each of the objects in the tree by 
using the following procedure: 

1. Examine the ob—head field of the current object. If there's a 
child, visit it by making it the current object. Then go back 
to Step 1. 

2. If there's no child, look at the ob—next held. If this field con- 
tains a NIL (—1) value, you're back at the root object, and 
your tour is finished. 

3. If the value in ob_next is not NIL, check to see if the object 
it points to contains the number of the current object in its 
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ob—tail field. If it does, we've moved back up to the parent 
of the current object, so make it the new current object and 
go back to Step 2. 

4. If the value in ob_next is not NIL, and does not point to an 
object whose ob_tail is the same as the current object, then 
it points to a sibling object which you haven't visited. Visit 
this object by making it the current one, and go back to 
Step 1. 

The AES performs many of its tasks by following the ob- 
ject tree. For example, it can draw the entire tree by starting at 
the root and then drawing each object it visits as it walks 
around the tree. Your own program can also use these links to 
perform a specified operation on all of the members of a tree, 
such as changing all of their status flags. 

Although the scheme used to link GEM objects together 
may seem complex, it actually simplifies many tasks which the 
AES must perform. To understand how, you must look at the 
last four fields of the object structure. 

Object Size and Position 

The final four fields of the object structure contain the position 
and size of the object, expressed in the standard format of x posi- 
tion, y position, width, and height. In this case, however, the x 
and y positions don't represent an absolute pixel coordinate. 
Rather, the position is specified as an offset from the x,y position 
of its parent object (whose own x,y position is an offset from its 
parent's position). Thus, each object inherits the origin position of 
its parent. Changing the position of a parent object also changes 
the positions of all of its descendants. 

The relative positioning of objects within their parent's 
rectangle is just one aspect of the principle known as the vi- 
sual hierarchy of GEM objects. This principle states that the 
rectangle of each parent object completely contains the rectan- 
gles of all of its children. Since each parent rectangle contains 
all of its child rectangles, it stands to reason that when the 
parent object moves, so must the children. 

One of the most important tasks which the AES must per- 
form in order to maintain the system of GEM objects is find- 
ing which object rectangles (if any) overlap a given x,y 
location on the screen. The hierarchy of GEM objects greatly 
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simplifies this task, by breaking the screen down into a num- 
ber of significant rectangles. The largest of these is the rectan- 
gle of the root object. If the location doesn't lie within the root 
rectangle, it can't coincide with any object in that tree. If it's 
within the root, the AES then checks it against the rectangles 
of the first level of siblings. If it lies within one of those rect- 
angles, the AES keeps moving down the tree until it finds the 
smallest object whose rectangle contains the point in question. 

But if the point doesn't lie within the rectangle of a par- 
ticular parent object, the AES can forego checking any of its 
children, since none of the children can contain a point that 
isn't located within the parent. You should note that while the 
object tree hierarchy insures that a child will be selected over 
its parent, it doesn't prevent two siblings from overlapping. If 
they do, and the user clicks in the overlap area, the AES will 
find the last or "rightmost" sibling (according to the tree dia- 
gram). That's why you can use an L_BOX sibling to cover 
other siblings so that all will appear to be selected at once (as 
you'll see later in the section on box- type objects). 

The tree structure also helps the AES in drawing object 
trees. The visual hierarchy insures that smaller objects are al- 
ways drawn after larger objects, so the larger parent won't 
cover up its smaller children. As you'll see later, the 
objc—draw() function that draws an object tree allows you to 
specify a clipping rectangle within which the objects will be 
drawn. Because of the tree structure, this drawing routine can 
automatically skip drawing any child object if its parent is not 
within the clipping rectangle. 

The usefulness of the mouse rectangle event becomes 
much more apparent when considered in the light of the ob- 
ject tree structure. Using parent objects to contain subobjects 
allows you to divide the screen into large rectangles which can 
be used as mouse rectangles. These can be further subdivided 
into large areas containing several child objects each. Once the 
user has clicked in the largest rectangle, you can follow the 
object tree into smaller and smaller rectangles, eliminating on 
the way all objects that are not within the parent rectangles. 
This strategy lies at the heart of the point-and-click operation 
of GEM. 
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Types of GEM Objects 

The ob—type field in the object data structure is used to de- 
scribe the type of object. The standard GEM object types, and 
their macro names (from the OBDEFS.H file), are as follows: 


Type 

Macro 


Number 

Name 

Description 

20 

G_BOX 

An opaque box (with optional border) 

21 

G-TEXT 

A formatted text string for which you may 
specify color, font size, and horizontal 
positioning 

22 

G-BOXTEXT 

A formatted text string within an opaque 
box (with optional border) 

23 

G—IMAGE 

A monochrome graphic bit-image 

24 

G—PROGDEF 

A user-defined object type 

25 

G—IBOX 

A transparent box (with optional border) 

26 

G-BUTTON 

A G_STRING (see below) with a border 
around the text 

27 

G—BOXCHAR 

A single text character within an opaque 
box (with optional border) 

28 

G_STRING 

A string of black graphics text, in the de- 
fault font 

29 

G-FTEXT 

An editable text field, for which you may 
specify a template, a validation string, and 
an initial value. 

30 

G—FBOXTEXT 

An editable text field within an opaque 
box (with optional border) 

31 

G—ICON 

An object consisting of a monochrome bit- 
image and an image mask used for for 
drawing the image in normal and inverse 
video modes 

32 

G-TITLE 

A specially formatted G_STRING for use 
in the title bar of menus 


As you can see, the various objects types are mainly made 
up of combinations of rectangular boxes, text forms, and bit- 
images. Each of the object types will be examined in detail be- 
low. At the same time, there will be an examination of the 
obspec data field which contains either two words of object- 
specific information, or a pointer to an object-specific infor- 
mation block. A point which may be of interest to you is that 
the AES doesn't use the top byte of the object type field. Pro- 
grammers are free to use this byte to create their own ex- 
tended object types, which contain additional information 
about the object. 
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Box Objects 

The three box object types are G_BOX, B_ IBOX, and 
B-BOXCHAR. 

G_ BOX. The first, G_BOX, is a solid rectangle with an 
optional border. The box may be filled either with a solid 
color or a pattern. A G_BOX is generally used as a backdrop 
on which to place other objects. The dialog box illustrated in 
Figure 4-1, for example, uses a G_BOX for the root object 
ROOTBOX, the plain white box on which the entire dialog is 
mounted. It also uses a patterned G—BOX (PATBOX) as a pat- 
terned backdrop for the three buttons and the text. 

G—IBOX. The second type of box object, G—IBOX, is a 
transparent box with an optional border. If the thickness of 
the border is set to 0, the box is truly invisible, as its name 
suggests. A G—IBOX is most often used to group together 
other objects. For example, in the dialog box of Figure 4-1, the 
three radio buttons marked A, B, and C are contained in an in- 
visible G—IBOX called INVISBOX. Since radio buttons must be 
siblings (as you'll see later on), the G—IBOX is used as an in- 
visible common parent. Another possible use for a G—IBOX is 
to group together two or more objects in order to make any of 
them select all of them. For example, say that two sibling ob- 
jects — one an image and the other a text string — are placed 
near each other. If you cover them with a higher-numbered 
sibling G—IBOX, both will still show through, since the 
G—IBOX is transparent. But clicking anywhere in the box will 
highlight both the image and the string. 

G_ BOXCHAR. The final box object, G_ BOXCHAR, is an 
opaque box like B_ BOX, only with a single text character drawn 
in the center of the box. The G_ BOXCHAR type of object is 
used by GEM for the various window controls, such as the 
sizer, fuller, and closer. In the example dialog, G_ BOXCHARs 
were used for the three radio buttons, BUTNA, BUTNB, and 
BUTNC. 

The obspec field for each of these box type of objects 
contains two words of data that describe the color of the ob- 
ject, and the thickness of its borders. The low word is used for 
the object color: 
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Bit 

Numbers Contents 
0-3 Interior color (0-15) 

4-6 Interior fill pattern 

0 Background color (IP_HOLLOW) 

1-6 Dither patterns of increasing darkness (IP_1PATT to 
IP—6PATT) 

7 Foreground color (IP_SOLID) 

7 Writing mode 

0 Transparent 

1 Replace 

8-11 Border Color (0-15) 

12-15 Text Color (0-15) 


The names in parentheses next to the interior fill pattern 
codes are the macro names given for these patterns in 
OBDEFS.H. The default colors and their macro names are 
listed below: 


Color 

Number Name 

0 White 

1 Black 

2 Red 

3 Green 

4 Blue 

5 Cyan 

6 Yellow 

7 Magenta 

8 Low white (light gray) 

9 Light black (dark gray) 

10 Light red 

11 Light green 

12 Light blue 

13 Light cyan 

14 Light yellow 

15 Light magenta 

These colors are only the default values. The color con- 
tained in any particular color register can be changed by the 
user at any time from the Control Panel desk accessory. These 
colors may also be changed by a program that uses the 
vs—Color( ) command. It's worth noting that while any color 
number in the range 0-15 is valid, medium resolution screens 
can only display the first four colors, while monochrome 
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screens are limited to the first two. Any out-of-range selections 
will be treated as color 1 (black) on these displays. 

The low byte of the high word of the ob_spec field of box 
objects is used for the thickness of the border: 

—127 to —1 Outside thickness in pixels outward from object's edge 

0 No thickness 

1 to 128 Inside thickness in pixels inward from object's edge 

Since the VDI drawing routines used to render wide lines 
only respond to odd-numbered settings, the border thickness 
value that you specify should be an odd number. 

The high byte of the high word is used only for the 
G—BOXCHAR object type. It contains the ASCII value of the 
character drawn in the box. The chart in Figure 4-3 summa- 
rizes the flags stored in the 32-bit objc_spec field of box 
objects. 


Figure 4-3. Summary of Flags Stored in 32-Bit Objc-Spec Field of 
Box Objects 

1 Uriting 
Mode 

0 : Transparent 

1 = Replace 

lit" 

7 



ASCII value 
of G.BOXCHAR 
character 


L -s^ J 


Border Thickness 
negative = outside 
Zero s none 
Positive = inside 


Bits 

15-12 

Border 

Color 


Bits 

11-8 

Text 

Color 

Bits 

6-4 

Bits 3-0 

Pill 

Pattern 

0 = hollow 
1-6 = dithered 
7 = solid 

Interior 

Color 


Text String Objects 

The next group of objects, G_STRING, G—BUTTON, and 
G—TITLE, contain text strings. All three of these object types 
use the plainest text, drawn in the default size of the system 
font, with black as the text color, and with no special effects 
such as italics. 
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The ob_ spec field of all of the string objects contains a 
pointer to the string. This pointer is the long-word address of 
the first character of the text. The string must follow the C lan- 
guage convention of ending in the ASCII 0 character. 

G_ STRING. The G_STRING type is used for fixed, 
explanatory text. 

G-BUTTON. The G-BUTTON is one of the most fre- 
quently used types of objects. It's like a G_STRING with a 
one-pixel border drawn around the text. As you will see be- 
low, the width of this border is increased if certain attribute 
flags such as DEFAULT are set. Buttons are most often used as 
controls the user can click on. For example, the OKBUTTON 
object in the sample tree was a G_ BUTTON type of object 
that the user could click on to end the dialog. In addition to 
buttons that exit the dialog, like OK and CANCEL, these ob- 
ject types can be used as Boolean on-off switches, allowing the 
user to select an option or to deselect it. 

G—TITLE. The last type of string object is the G—TITLE. 
This is a string object which is specially formatted for use in 
the title bar of menus. Its special formatting insures that the 
menus are redrawn correctly. 

Formatted Text Objects 

The next group of text objects, G—TEXT, G—BOXTEXT, 

G_ FTEXT, and G—FBOXTEXT, are a little bit fancier than the 
previously mentioned string objects. All of these objects allow 
you to select normal or small text, different text colors, and 
horizontally justified type. In addition, two of them allow you 
to specify ways the user will be able to edit the text string. 

G—TEXT and G-BOXTEXT. The first two, G-TEXT and 
G—BOXTEXT, are just fancier versions of the G_ STRING and 
G_ BUTTON types. G—TEXT is a colored text string, while 
B_ BOXTEXT is a formatted text string surrounded by a border. 
These object types can be used in place of the simpler string 
objects when you want to use a text color other than black, a 
smaller text font size, or if you need horizontal positioning to 
take place when the program executes. Since they require 
more memory than the G_ STRING and B—BUTTON types 
and, because too much color can distract the user, you should 
exercise discretion in the use of these object types. 
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G-FTEXT and G-FBOXTEXT. G_FTEXT and 
G—FBOXTEXT are editable versions of G—TEXT and 
G—BOXTEXT. This doesn't mean that they're inherently edit- 
able. Rather it means that you supply enough information 
about them to allow Library routines like form—do( ), which 
handles all dialog activity, to supervise editing by the user. 
The editing information you supply consists of a template 
which determines the text format, a validation string that 
shows which characters may be entered in which positions, 
and an initial or default value for the string. 

Editing and display information is stored in a data struc- 
ture called a TEDINFO. The ob_spec field of text type objects 
contains a pointer to the object's TEDINFO. The C language 
definition of this data structure is as follows: 


typedef struct text_edinfo 

{ 


char 

*te_ptext; 

/* pointer to the actual text string */ 

char 

*te_ptmplt; 

/* pointer to format template */ 

char 

*te_ pvalid; 

/* pointer to validation string */ 

int 

te_ font; 

/* font size (3 = normal, 5 = small)*/ 

int 

te— resvdl; 

/* reserved word */ 

int 

te_ just; 

/* horizontal justification— left, right... 

int 

te_ color; 

/* color information word */ 

int 

te_resvd2; 

/* reserved word */ 

int 

te_thickness; 

/* border thickness */ 

int 

te_txtlen; 

/* length of text string */ 

int 

te_ tmplen; 

/* length of template string */ 


} TEDINFO; 

The first three fields are four-byte pointers to text strings. 
The first, te—ptext, is a pointer to the actual text string. This 
string may be composed of either text characters or blank 
spaces. Note that the commercial at sign (@) is treated as a 
special case. If it appears as the first character in the string, the 
entire string is considered to be composed of spaces. While 
this is handy for the programmer, if the user edits the first 
character of the string to this symbol, the string will be blank 
the next time the text object is displayed. 

The next field, te—ptmplt, is a pointer to the template 
string. This string controls the format in which the text field is 
displayed. It is composed of constant text characters that won't 
be edited and underscore characters which indicate the posi- 
tion of at which the editable text is entered. For example, say 
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that the editable field is being used for the entry of a tele- 
phone number. The template string might be "Phone 

Number:( ) - ". If the initial string was 

"1234567890", the text object would be printed as "Phone 
Number:(123)456-7890". If the initial string did not have 
enough characters to fill out the template string, the unfilled 
underscore characters would be printed. 

The third field, te—pvalid, is a pointer to the validation 
string. This is a string that shows which type of character may 
be entered at a given character position. This string is com- 
posed of special validation characters, each of which stands for 
a class of allowable input: 


Validation 

Character 

9 

a 

n 

P 

A 

N 

F 

P 


X 


Input Accepted 

Numeric digits 0-9 only 

Upper- and lowercase alphabetic characters and the space 
character 

Numeric digits 0-9, upper- and lowercase alphabetic char- 
acters, and the space character 

All valid DOS pathname characters, including the colon (:) 
and backslash ( \) 

Uppercase alphabetic characters and the space character 
Numeric digits 0-9, uppercase alphabetic characters, and 
the space character 

All valid DOS filename characters, including the colon (:), 
and wildcard characters question mark (?) and asterisk (*) 
All valid DOS pathname characters, including the colon (:), 
the backslash ( \), and wildcard characters question mark 
(?) and asterisk (*) 

Any character 


In the telephone-number example, you would use a vali- 
dation string of 9999999999, since you only want to allow the 
user to enter a number in the blanks. 

The next field in the TEDINFO structure is te—font. This 
field allows you to select the normal-sized system font that's 
used to draw menu items or the small-sized font that's used to 
draw the text under the icons on the Desktop. A value of 3 se- 
lects the normal text font, while a value of 5 selects the small 
text font. The next field, te—resvdl, is reserved for future use. 
After that comes te—just, which contains a flag indicating the 
type of horizontal text justification used. A value of 0 selects 
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left-justified text, a value of 1 selects text that is right-justified. 
A value of 2 indicates that the text should be centered. 

The te— color field is a word of bit flags that identifies the 
color and pattern used for box type objects. Its format is ex- 
actly the same as the low word of the ob_spec field for the 
box objects, described above. The te— thickness field is used 
to describe the thickness of the border surrounding the 
G—BOXTEXT or G—FBOXTEXT. Its format is the same as that 
of the low byte of the high word of the ob_spec for box object 
(negative numbers to —127 show the outside thickness in pixels, 
positive numbers to 128 show the inside thickness in pixels). 

The last two fields in the TEDINFO structure are te—txtlen 
and te—tmplen. These fields specify the length of the text 
pointed to by te_ptext, and the length of the template string 
pointed to by te—ptmplt. These string sizes should include the 
null character (ASCII 0) used to terminate each string. 


Bit-Image Objects and Icons 

The next object type, G—IMAGE, is a simple monochrome bit- 
image object. This type of object is usually used to display a 
picture that's not meant to be selected by clicking the mouse 
on it. The reason these objects usually aren't selectable is be- 
cause only a single bit-plane image is supplied, so selecting 
them causes the whole rectangle around the image to be in- 
verted. Examples of bit-image objects are the drawings used to 
illustrate the Note, Wait, and Stop alert messages. 

The ob-spec field of a G—IMAGE contains a pointer to a 
data structure called a BITBLK. The C language definition of 
this data structure is 


typedef struct bit— block 

{ 


int *bi_ pdata; 
int bi_ wb; 

int bi_ hi; 

int bi_ x; 

int bi_ y; 

int bi_ color; 


/* pointer to bit-image data array */ 

/* width of bit image in bytes */ 

/* height of bit image in scan lines */ 

/* Image X offset from start of data block */ 
/* Image Y offset from start of data block */ 
/* foreground color of image */ 


} BITBLK; 
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The bi—pdata field contains a pointer to the bit-image data ar- 
ray. This array must be composed of 16-bit words. Therefore, the 
image's width in pixels must be an even multiple of 16. The bit- 
image data uses a simple coding scheme, where each bit repre- 
sents a pixel set to the foreground color (1) or the background 
color (0). The next field, bi—wb, gives the width of the bit image 
in bytes. Since the data array is composed of words, this field 
must always contain an even number. The bi—hl field contains the 
height of the bit image in scan lines. The fields bi-x and bi—y 
allow you to specify an x and y offset from the beginning of the 
image data array. This allows you to use only a portion of the im- 
age data for the object's bit image. The last field, bi— color, allows 
you to select the color used to draw pixels that represent the bits 
that are set to 1. Although the image itself is all the same color, 
this color need not be restricted to black. Any color register from 0 
to 15 is valid, although in medium and high resolutions, out-of- 
range numbers will be converted to 1 (black). 

There is another, more sophisticated type of bit-image ob- 
ject called a G—ICON. This type of object not only uses a bit- 
image data array, but an image mask as well. This image mask 
allows only the shape of the image to be highlighted when the 
object is selected. The G—ICON image may also contain a bit 
of explanatory text or an attached title, as well as a single text 
character superimposed somewhere on the image. Finally, it 
may specify both the color of foreground and background data 
bits. Examples of icon objects are easy to spot in the GEM 
Desktop program — all of the disk drive, trash can, file folder, 
and file image are G_ ICONS. 

The ob-spec field of a G—ICON type object contains a 
pointer to a data array called an ICONBLK. The C language 
definition for this data structure is 


typedef struct icon— block 

{ 


int 

*ib— pmask; 

int 

*ib_pdata; 

char 

*ib_ptext; 

int 

ib_char; 

int 

ib_xchar; 

int 

ib_ychar; 

int 

ib_ xicon; 

int 

ib_ yicon; 

int 

ib_wicon; 


/* pointer to the image mask data array */ 

/* pointer to the bit-image data array */ 

/* pointer to the object's text string */ 

/* low byte = ASCII character drawn on icon */ 
/* high byte = foreground and background colors 
/* the X offset of that character */ 

/* the Y offset of the character */ 

/* the X coordinate of the icon */ 

/* the Y coordinate of the icon */ 

/* the width of the icon in pixels */ 


7 
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int ib_hicon; 
int ib__ xtext; 

int ib_ytext; 
int ib_wtext; 
int ib—htext; 
} ICONBLK; 


/* the height of the icon in pixels */ 
/* the X offset of the text string */ 

/* the Y offset of the text string */ 

/* the width of the text in pixels */ 
/* the height of the text in pixels */ 


In order for you to understand the contents of the 
ICONBLK structure, you should first understand how the AES 
draws G—ICON images. An icon is composed of two bit im- 
ages, the mask and data images. The ib—pma$k field of the 
ICONBLK contains a pointer to the mask data array, while the 
ib—pdata field contains a pointer to the bit-image data array. 
When the AES draws the icon, it first draws the image mask, 
setting all of the pixels that correspond to 1 bits in the mask to 
the background color. It then draws in the data image, setting 
all of the pixels that correspond to 1 bits in the data to the 
foreground color. When the icon is selected, the AES high- 
lights the image by drawing the mask in the foreground color 
and the data image in the background color. The field 
ib—wicon contains the width of the icon image in pixels. Since 
the mask and image data arrays are composed of 16-bit words, 
this width must be an even multiple of 16. The ib—hicon field 
contains the height of the icon in pixels. The ib—xicon and 
ib—yicon fields contain the x and y coordinates of the icon im- 
age, relative to the data arrays. 

As mentioned above, you may specify a text string to ap- 
pear with the icon image, such as the filename that appears 
under the file icons on the Desktop. This text string is printed 
using the small size of the system text font. The ib—ptext field 
contains a pointer to the null-terminated text string itself. The 
ib— xtext and ib—ytext contain the x and y offsets for the start of 
the text, relative, to the upper left comer of the icon itself. And 
the ib—Wtext and ib—htext fields contain the width and height, 
respectively, of the text string in pixels. 

You may also specify a text character to appear with the 
icon image, such as the drive numbers that appear on the file 
drawer icons on the Desktop. The low byte of the ib—char field 
contains the ASCII value of the text character to appear with 
the icon. The ib—xchar and ib—ychar fields contain the x and y 
offsets for the character, relative to the top left comer of the 
icon. 

Although not noted in the GEM documentation, the high 
byte of the ib— character field contains the foreground and 
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background color indices. The upper four bits select the fore- 
ground color, while the lower four bits select the background 
color. While it's possible to select any combination of fore- 
ground and background colors, in order to retain compatibility 
across display modes and in the interests of good taste, you'll 
almost always want to stick with black for the foreground 
color and white for the background. 

User-Defined Objects 

The final object type is the most flexible of all. It is the user- 
defined object type, G—PROGDEF (in some versions of the 
OBDEFS.H file, the macro name for this type may be 
G—USERDEF). This type allows the programmer to create ob- 
ject types with an appearance different from the standard box, 
string, or image objects. For example, you might create an ob- 
ject type that consists of a box with rounded comers or a circle. 

The ob—spec field of a G—PROGDEF object contains a 
pointer to a data structure called an APPLBLK (in some ver- 
sions of OBDEFS.H it may be called a USERBLK). The C lan- 
guage definition of this data structure is 

typedef struct appl—blk 

{ 

long (*ub_code)( ); 

long ub_ parm; 

} APPLBLK; 

As you can see, it consists of two long word values. The 
first is a pointer to the function supplied by the user for draw- 
ing the object. The second is a user-defined parameter that's 
passed to the routine when the drawing takes place. This pa- 
rameter is passed as part of a larger block of information 
called a PARMBLK structure. 

The AES calls the user-defined drawing function when- 
ever the G—USERDEF needs to be drawn or modified. This 
occurs when the objc—draw( ) routine is used to draw the ob- 
ject, or the objc—change( ) routine is used to change its state. 
Say, for example, the ub—code field of an object's APPLBLK 
points to the function user—draw( ). Whenever that object is 
due to be drawn, the AES calls user— draw( ), and passes it a 
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pointer to a PARMBLK structure. The C language definition of 
this structure is 


typedef struct parm_blk 

{ 


OBJECT *pb_tree; 

r 



r 

int 

pb—objc; 

/• 

int 

pb_prevstate; 

r 

int 

pb_cnrr8tate; 

r 

int 

pb— x. 

r 


pt>-y. 



pb_ w. 



pb— h; 


int 

pb— xc, 
pb— yc, 

pb_wc, 

pb_hc; 

r 

long 

pb—parm; 

r 


r 

} PARMBLK; 


Pointer to the object tree */ 
containing this object */ 

This object's index in the tree */ 

The object's previous (old) state field */ 
The object's current (new) state field */ 
The position and size of the object */ 


The position and size of the clip rectangle 


The contents of the ub_parm field */ 
in the APPLBLK */ 


7 


This structure gives the drawing function much of the infor- 
mation needed to draw the object. The pb—tree field contains a 
pointer to the object tree that contains this object, and the pb—objc 
contains the object number of that object within the tree. The 
pb—prevstate and pb—currstate fields contain the previous and cur- 
rent values for the object's state flag (the possible state values will 
be discussed below). If the previous and current states are the 
same, the application is drawing the object. If they are different, 
the application is changing the object's state. 

The next eight words contain rectangle information for the 
object and for the current clipping rectangle. The object's x 
and y positions given here represent the actual pixel position 
of the object, not an offset from its parent. The clipping rec- 
tangle, likewise, represents a rectangle on the physical screen. 
The last field in the PARMBLK structure is called pb—parm, 
and it contains whatever value you placed in the up—parm 
field of the APPLBLK structure. 

To summarize, when you define a G—PROGDEF type ob- 
ject, you place a pointer to an APPLBK structure in its 
ob__spec field. That APPLBLK contains the address of a draw- 
ing routine and a long word parameter. When the object must 
be drawn, or when its state field changes, the AES calls your 
drawing routine. The AES passes a pointer to your drawing 
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routine which points to a PARMBLK, containing information 
about the object's size, position, and state. For example, if 
your APPLBLK points to a drawing routine called user—code(). 
This routine would be defined like this: 

user_code(pb) 

PARMBLK *pb; 

read— parms( ) /* read whatever parameters necessary from 
PARMBLK */ 

do_ draw( ) /* draw the object, or whatever else you want to 

do */ 

return(O) /* your routine should always return a value of 


A few words of caution are in order about what your 
drawing code can contain. First, your routine is being called by 
the AES and uses the AES's stack. Therefore, avoid program- 
ming techniques which use a large amount of stack space. For 
instance, you will probably want to avoid using long param- 
eter lists or recursion. 

Second, the AES is not reentrant, and so you may not call 
AES routines from within your drawing code (VDI routines are 
all right). 

Finally, your routine should always return a value of 0 to 
the AES. This signals that everything's all right. If any other 
value is returned, the AES drawing operation will halt, and 
the other objects in the tree won't be drawn. 

Object Flags 

The next data field in the object structure is called ob— flags. 
This field is used to specify attributes for the object which in- 
dicate how the user should be able to interact with it. This in- 
teraction is usually carried out by means of AES Library 
routines such as form—do( ), which controls all of the user inter- 
action during dialogs. This routine examines the various object 
flags and implements their functions. 

The object attributes are set up as bit flags, which means 
that each is assigned a bit in the word ob_flags. If the bit is 
set to 1, the object has the attribute, and if it's reset to 0, the 
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object doesn't. The full list of bit flags and the macro name as- 
signed them in the OBDEFS.H header file is as follows: 


Bit 

Bit 

Macro 

Description 1 — i 

of Attribute 1 | 

Number 

Value 

Name 

0 

1 

SELECTABLE 

The user can select the object by 
clicking on it. A change in graphics, 
such as color inversion, should in- [ 

dicate the selected state. 

1 

2 

DEFAULT 

The user can select the object from 
a dialog by pressing Return key. 
There must only be only one object 
with this flag per tree, and some 
graphic change, such as thickening 
of die button border, should indi- 
cate that this object is the default. 

2 

4 

EXIT 

Selecting this object indicates that 
the user wishes to exit the dialog. 

3 

8 

EDITABLE 

Indicates the user is able to edit the 
object in some way (such as chang- 
ing the text string). 

4 

16 

RBUTTON 

This object is one of a set of radio 
buttons. Radio buttons are sibling 
objects whose selection is mutually 
exclusive — selecting one automati- 
cally deselects the others. 

5 

32 

LASTOB 

The object is the last one in the ob- 
ject tree. 

6 

64 

ToucHExrr 

Indicates that the form_do( ) rou- 
tine will return control to the pro- 
gram as soon as the user presses 
the mouse button with the mouse 
touching the object, without wait- i — i 

ing for die button to be released as ! 

with EXIT. 

7 

128 

HIDETREE 

Makes a subtree invisible. Object li- p— . 

brary calls will not draw or find the | j 

object or any of its children. 

8 

256 

INDIRECT 

This flag to show that the value in 

ob_spec is actually a pointer to the 
real value of ob_spec. 


n 

n 
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The SELECTABLE flag. The SELECTABLE flag is an im- 
portant one. If this flag is set, the user can select the object by 
moving the mouse pointer over it and clicking the left mouse 
button. When this happens, the AES changes the flag which 
indicated whether the item is selected (see the SELECTED 
flag, below) and redraws the entire object rectangle in reverse 
video to highlight the object. The select mechanism works as a 
toggle. If the object is selected and the user clicks on it, it is 
deselected. While the AES takes care of the details of updating 
the object state flag and the video display, it is up to the appli- 
cation to check the SELECTED flag and, if it is set, perform 
the specified task. 

The DEFAULT flag. A related flag is the DEFAULT flag. 

The form_do( ) library function uses this flag in handling key- 
board events during a dialog. If the Return key is pressed, the de- 
fault object is automatically selected, and the dialog is concluded. 
Note that the default object may be selected even if the 
SELECTABLE flag is not set or if the DISABLED state flag is set, 
and that selecting the default object with the Return key causes 
the dialog to exit whether or not the EXIT flag is set for this ob- 
ject. The AES makes some default objects (such as buttons or 
boxes with an outside border) visually distinct by thickening the 
border surrounding them by one pixel. For that reason, you 
should only set the DEFAULT flag for one object in a dialog, 
since the AES will only select the first default object it finds, and 
you don't want to mislead the user into thinking that another one 
is the default. In a dialog, you'll often see a button such as OK or 
CANCEL with a thick box around it, indicating that it's the de- 
fault object. 

The EXIT flag. The EXIT flag indicates that the AES Li- 
brary routine form_do( ) will exit a dialog when this object is 
selected by moving the mouse pointer over it and clicking the 
left mouse button (the SELECTABLE flag must also be set). As 
with default objects, the AES makes some exit objects visually 
distinct by thickening the border surrounding them by one pixel. 
If both flags are set, the border around the default object is 
thickened by two pixels. You'll often see a dialog with buttons 
like OK and CANCEL where the borders of both are thick- 
ened, but that of the default button is the thicker of the two. 

The EDITABLE flag. The EDITABLE flag is used to indi- 
cate that an object may be edited by user interaction. The 
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form_do( ) library routine in particular uses this to locate edit- 
able text objects. This helps the form_do( ) keyboard handler 
routine to find the next editable text field when the user 
presses the Tab or Shift-Tab key combinations. 

The RBUTTON flag. Sometimes in a dialog, you wish to 
present a number of options which are mutually exclusive. For 
example, in a communications terminal program, you might 
want to allow the user to set the data transfer speed to 300, 
1200, or 2400 bits per second. Therefore, it's handy to be able 
to indicate that the act of selecting some objects will automati- 
cally deselect others. The RBUTTON flag is used for just this 
purpose. It indicates that the object is a radio button, named 
for the push buttons on a car radio which pop up when a new 
one is pushed. In order to indicate which other objects share 
this mutual exclude feature, radio buttons must be siblings. 
Radio button objects are normally set up by creating a box ob- 
ject, such as a G_BOX or G—IBOX, and placing the buttons in- 
side. The sample dialog box of Figure 4-1 is arranged this way, 
with BUTNA, BUTNB, and BUTNC all children of the invisi- 
ble INVISBOX. 

The LASTOB flag. The LASTOB flag merely indicates 
that an object is the last one in its object tree. 

The TOUCHEXIT flag. The TOUCHEXIT flag is an inter- 
esting variation on the normal EXIT. When this bit is set in an ob- 
ject's ob_flag field, form_^do( ) exits as soon as you move the 
mouse over the object and press the left mouse button. It does not 
wait until the mouse button is let up again, as it does for exit ob- 
jects. This allows you to create your own scroll bars or other 
dragable or autorepeat controls within a dialog. While the AES 
doesn't wait for the button to be released on a TOUCHEXIT ob- 
ject, it does test to see if it has been released. If it finds that the 
button was released, it waits to see if the user double-clicks. When 
it detects a double-dick, it sets the high bit of the object number 
returned from form_do( ). Therefore, your program code should 
be prepared to deal with the possibility that the user will double- 
click on a TOUCHEXIT object. At the very least, it should mask 
off the top bit of the object number returned by form__do( ) if it 
doesn't care about double-clicks. Of course, you can always use 
the double-dick condition to enhance the function of the object, 
like allowing the user to double-dick on a filename to open the 
file immediately. 
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The HIDETREE flag. The HIDETREE flag is used to 
make part of an object tree invisible. Whenever the 
objc—draw( ) or objc—find( ) routines are called, the AES will not 
draw or find this object or any of its descendants. 

The INDIRECT flag. Finally, the INDIRECT flag is used 
to change the meaning of the ob_spec field. When INDIRECT 
is set, ob_spec is interpreted as a pointer to the actual 
ob_spec data. This allows you make the actual ob_spec part 
of a larger block of user-defined data, with the new ob_spec a 
pointer to that data block. 

Object States 

The final field in the object structure is called obstates. The 
state of an object determines what the application does with it, 
as well as the way it's drawn by the library routine objc-draw( ). 
This field, like the flags field, is made up of bit flags. The vari- 
ous flags and their macro names (from the OBDEFS.H header 
file) are listed below: 

Bit Bit Macro 

Number Value Name Description 

0 1 SELECTED The object is highlighted, usually 

by inverting the foreground and 
background colors. 

1 2 CROSSED For a box-type object, indicates 

that an X is drawn in the box. 

2 4 CHECKED Indicates that a text object such 

as a menu title is drawn with a 
checkmark in front of it. 

3 8 DISABLED Indicates that the object (typically 

a menu title) is drawn faintly by 
masking out every other pixel. 

4 16 OUTLINED An outline is drawn around a box 

object. 

5 32 SHADOWED The object (usually a box) is 

drawn with a drop shadow. 

The SELECTED flag. The SELECTED flag indicates that 
the user has selected this object, usually by moving the mouse 
pointer over it and clicking the left button during the course of 
a dialog. When the objc_state( ) function is used to change an 
object's state to selected, the AES visually highlights the ob- 
ject, usually by inverting the foreground and background col- 
ors in its rectangle. Icons are the exception to this rule, in that 
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their image and mask colors are inverted, not the colors of 
their entire rectangle. 

The CROSSED and CHECKED flags. The CROSSED 
and CHECKED flags are generally used to manage an alter- 
nate system of highlighting a selected object. CROSSED is 
used with filled box objects to draw an X in the box using the 
background color. By setting the TOUCHEXIT flag, the appli- 
cation can easily toggle the CROSSED flag, turning the X on 
or off. 

The CHECKED flag is used with text boxes, such as those 
found in menu items. It places a checkmark in front of the 
text. The Menu Library routines include menu—icheck() which 
is used to display or erase the checkmark in front of menu 
items. 

The DISABLED flag. The DISABLED flag is used to indi- 
cate that an object (usually a menu item or button) may not be 
selected. The AES draws a DISABLED object faintly, by super- 
imposing a crosshatch of white dots over it. The form_do( ) 
routine will not allow the user to select a DISABLED object by 
clicking on it, though it will allow the selection of a DEFAULT 
DISABLED object by pressing Return. 

The OUTLINED and SHADOWED flags. The final two 
states, OUTLINED and SHADOWED are used mostly for cos- 
metic enhancement of container-type box objects. The OUT- 
LINED state causes the AES to draw the object with a thin 
outline around it. Combined with a two- or three-pixel inner 
border, this gives the object an attractive frame. 

The SHADOWED state causes the AES to draw a drop 
shadow under the object. This is a two-pixel line drawn under- 
neath and to the right of the object. Root objects of dialog 
boxes often have a drop shadow under them. 

Object Library Routines 

The AES provides a number of low-level routines for dealing 
with objects. The most basic routine draws an object tree. 
You'll recall that an object tree is a linked array of object data 
structures. It's called objc—draw( ). Here is how it is called: 

int status, firstob, depth, clipx, clipy, dipw, cliph; 
struct object tree[ ]; 

status = objc_draw(tree, firstob, depth, clipx, clipy, clipw, cliph); 
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This function draws the object tree whose address is con- 
tained in the pointer tree, starting with the object whose index 
number is in firstob and going down as many generations as 
specified in the depth variable. If you want the whole tree 
drawn, you may use ROOT (defined as 0) for firstob and 
MAX-DEPTH (defined as 8 in OBDEFS.H) as the depth vari- 
able. This function also allows you to specify a clipping rectan- 
gle, whose position and size are given in clipx, clipy, clipw, and 
cliph. Only those portions of objects which are contained 
within the clipping rectangle will be drawn. As explained in 
connection with window refresh, this clipping function can be 
very handy for redraws of objects contained within windows. 
The error status of the routine is returned in the status vari- 
able. As with all of these routines, a status of 0 indicates that 
an error occurred, while a positive integer indicates that there 
was no error. 

Another basic function is used to find the index number 
of the object located at a certain x,y coordinate on the screen. 
This is handy for determining whether the mouse pointer is 
positioned over an object when the user presses the button. 
This function is called objc—find( ), and its syntax is as follows: 

int foundob, firstob, depth, x, y; 
struct object tree[ ]; 

foundob = objc_find(tree, firstob, depth, x, y); 

where tree is a pointer to the tree you want to search, firstob is 
the index number of the object you wish to begin the search 
with, and depth is number of generations down the tree you 
wish to search. The variables x and y hold the screen coordi- 
nates of the object you're searching for, usually the current x 
and y positions of the mouse pointer. If objc_ find( ) locates an 
object at those coordinates, it returns the object number of the 
last object found in the foundob variable. If it doesn't find any 
objects there, it returns a value of —1. 

The objc—offset() function is the opposite of objc_find( ). It 
starts with the object number, and returns the absolute screen 
position of that object. This function is necessary because you 
can't determine the x and y coordinates of an object just by 
looking in the ob—x and ob—y fields of its object structure. The 
positions stored there are relative offsets from the object's par- 
ent, so to determine its absolute position, you must add all of 
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the offsets of each preceding generation to the x and y position 
of the root. The syntax for the objc_offset( ) call is 

int status, object, x, y; 
struct object tree[ ]; 

status = objc_offset(tree, object, &x, &y); 

where tree is a pointer to the object array, object is the index 
number of the object whose position is desired, and x and y 
are the variables in which that position is returned. 

The objc— change function is used to change the obstatus 
field of an object, and, optionally, to redraw it at the same 
time. It's called like this: 

int status, object, reserved, clipx, clipy, clipw, cliph, state, redraw; 
struct object tree[ ]; 

status = objc— change(tree, object, reserved, clipx, clipy, clipw, 
cliph, state, redraw); 

where tree is a pointer to the object tree, object is the number 
of the object to be changed, and state is the new ob_state flag 
value. The redraw flag is used to indicate whether or not the 
object should be immediately redrawn; a 1 indicates that the 
object should be redrawn, while a 0 indicates that it should 
not. If the object is redrawn, the clipx, clipy, clipw, and cliph 
variables are used to set the clipping rectangle prior to the 
redraw. 

The objc—edit( ) function assists in the process of letting 
the user edit a text object. It's the low-level routine used by 
the dialog handler routine form_do( ) to implement text 
editing. The syntax of the objc_edit( ) call is 

int status, object, char, index, type; 
struct object tree[ ]; 

status = objc_edit(tree, object, char, &index, type); 

where tree is a pointer to the object tree, and object is the 
number of the text object to be edited. The char variable con- 
tains the character to be inserted into the text string (usually 
obtained by reading the keyboard and using the result as the 
input here). The index variable does double duty. As input, it 
gives the routine the offset that tells it what place in the string 
is being edited. When the function concludes, it returns the 
new index number in this variable. Finally, the type variable 
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contains a flag that indicates the type of editing function to be 
performed. The editing functions available are shown below.* 

Type 

Number Macro Name Description of Function 

0 ED—START Reserved for future use 

1 ED_JNIT Combine the template string of TEDINFO 

field te—ptmplt with the text string of the 
te—ptext field to display the formatted string 
and then turn the cursor on 

2 ED—CHAR Check the input character against the valida- 

tion string in TEDINFO field te—pvalid, up- 
date the te—ptext field if the input character 
is valid, and display the changed text 

3 ED—END Turn off the text cursor 

You may notice that the C calling sequence for objc_edit( ) 
above differs from the Digital Research documentation. In that 
version, there are separate parameters for the text string index you 
input and the index returned by the program. The extra index 
pointer is added to the end of the parameter list. As of this writ- 
ing, however, the Alcyon C bindings from Atari, and those derived 
from those bindings such as the Megamax compiler use the same 
index pointer for input and output. & you have problems making 
this function work correctly from C, you should examine either 
the source or a disassembly of your bindings, to determine the 
correct calling sequence. 

In order to perform text editing, the Library function 
form_do( ) calls objc_edit with the function type set to 
ED—INIT to display the cursor in the first field to be edited. It 
then uses an evnt—multH ) call to read the keyboard (among 
other things). When a key is pressed, it checks to see if it's one 
of the special keys, such as the cursor or Tab keys used to 
change to the next text field. If not, the string is edited by call- 
ing objc_ edit( ) with the type flag set to ED—CHAR. If the 
field to be edited is changed, the cursor is turned off in the 
current field with the ED—END function of objc_ edit, and the 
whole process is repeated with the next field to be edited. 

The final three basic object functions allow you to reorder 
the linkages in the object tree array, without manually chang- 
ing individual link fields. They are most useful for dynami- 
cally allocated object trees such as are used on the GEM 
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Desktop program, where it's not possible to determine ahead 
of time how many file icons will be needed in a window. If 
you set up your object trees ahead of time by using a resource 
file, as is usual, you won't have to worry about these calls. 

The first operation is objc—add( ), which is used to add an ob- 
ject as a child of a parent object. 

int status, parent, child; 
struct object tree[ ]; 

status = objc_add(tree, parent, child); 

where tree is a pointer to the object tree, parent contains the 
object number of the parent object to which you wish to link 
the child, and child contains the object number of the child 
you wish to link in. 

Likewise, you can remove an object from a tree altogether 
by using the objc—delete( ) function: 

int status, object; 
struct object tree[ ]; 

status = objc_delete(tree, object); 

where tree is a pointer to the object tree and object contains 
the object number of the object to be removed. 

Finally, you may change an object's order in relation to its 
siblings by using the objc—order( ) function: 

int status, object, newpos; 
struct object tree[ ]} 

status — objc_order(tree, object, newpos); 

where tree is a pointer to the object tree, object is the number 
of the object to reorder, and newpos is a flag which indicates 
how to reorder this object's siblings. A value of 0 specifies that 
the object is to be moved to the end of the chain of siblings, 1 
specifies that it be moved to a position second from the end of 
the chain, and so on. A value of — 1 can be used to indicate 
that the object should be moved to the position of first sibling 
in the chain. 

Program 4-1, written in C demonstrates the use of 
objc_draw( ) and objc_find( ), two of the more commonly 
used low-level object functions. It displays an object tree that 
consists of three objects — a root box, a text string, and a but- 
ton. It then waits for a mouse button press and checks to see 
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whether the mouse was over the button when the press oc- 
curred. If it was not, it waits for another button press. If the 
user clicks on the EXIT button, the program ends. 

Program 4-1. object.c 

/mtMitimttmtimtmmmttttmtmtmiimtummom/ 


f* */ 
/* OBJECT . C — Demonstrates the use of low-level */ 
/* Object Library functions on a pre-initial ized */ 
/t object tree array. */ 

/% %/ 
/* */ 


/tttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttt/ 


•define APP.INFO " " 

•define APP NAME "Object Example" 

•define WDW CTRLS <NAME) 

•define EXITBUTN 1 

•include "aesshell.c" 

char tstringsC3 “ C 
"EXIT", 

"Push Button to Exit">; 

OBJECT treeC3 » € 

C-l, 1, 2, Q_BOX, NONE, OUTLINED, 0X21100L, 6,5, 22,10>, 

€2, -I, -1, Q_BUTTON, SELECTABLE 1 DEFAULT t EXIT, 

NORMAL, stringsC03, 12,6, 8,1>, 

<0, -1, -1, G.STRINQ, LASTOB, NORMAL, stri ngsC 13, 1,2, 21,13 
>1 




□ 

U 


demo ( ) 
i 

int msgbufC83; 

int x, y, button, keys, object, state; 

evnt.mesage (Scmsgbuf ) ; /* skip the window redraw message, %/ 

for (x»0; x<3; x++> /* fix object x, y, width and height %/ 

< 

treeCx3.ob_x *= cellw; 
treeCx3.ob_y t«=* cellh; 
treeCx 3. ob_width *=» cellw; 
treeCx3 . ob.height cellh; 

> 

/% draw the object tree %/ 

ob jc_draw (tree, 0, 1, work.g_x, work.g_y, work.g_w, work.g_h); 

/* check for mouse button press over EXIT button */ 
do 

evnt_button ( 1 , 1 , 1 , Sex , &y, febutton, Stkeys) ; 
object = ob jc_f ind (tree, 0, 1, x, y) ; 

> 

while (object ! = EXITBUTN); /* keep checking 'til we find object 1 */ 
/* show object selected %f 

state = treeCEXITBUTND . ob_state ~ SELECTED; /% flip SELECTED bit »/ 
ob jc_change (tree, EXITBUTN, 0, 

work.g_x, work.g_y, work.g_w, work.g_h, state, 1); 


/ttttttttttttttttttttt End of Object.c **********************/ 
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Please note two points about this program: First, an array 
of object structs called tree was declared and initialized at the 
same time. The x, y, width, and height values could not be 
filled, however, since there is no way to know in which of the 
three display resolution modes the program would run. To 
solve this problem, the number of character cells the object oc- 
cupies was put into the x, y, width, and height fields. Then, 
when the program started, each of the x, y, width, and height 
values was multiplied by the default character cell width or 
height. This produced objects that occupied the same number 
of character cells regardless of the resolution mode (though 
these objects are twice as wide in low-resolution mode, since it 
only provides 40 characters per line). 

Setting up objects in this manner may be easy to demon- 
strate, but it's by no means the preferred method. Typing all 
of the data by hand and then manually linking the objects to 
each other and to their ob_spec fields is nobody's idea of fun. 
As you'll see in the next chapter, there's a much easier and 
more effective way to create object trees. 

For machine language programmers. Program 4-2 is a 
rough translation of the C sample program above. For the sake 
of brevity, the direct manipulation of the object x, y, width, 
and height fields was skipped in favor of using an AES Li- 
brary routine, rsrc—obfix( ), which does the same thing. This li- 
brary routine will be discussed in the next chapter. 

Program 4-2. objects 

************************************************************ 

* * 

* OBJECT. S Demonstrates low-level object calls * 

* * 
************************************************************ 

*** External references 

** Export: 

.xdef demo * external demo subroutine. 

.xdef wdwctrl * window controls 

.xdef wdwtitl * window title string 

.xdef wdwinfo * window info string 

** Import: 

.xref aes * the AES subroutine 

.xref ctrl0 * and the AES data arrays 

.xref Ctrl 1 

.xref Ctrl 2 

.xref ctrl3 

•xref Ctrl 4 

.xref addrin 


n 

□ 

n 


□ 

n 

n 

n 

n 
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aintin 

aintout 

work* t and the window work rectanglE 

worky 

workw 

workh 


ttt Fix object position and size -from characters to pixels 

move #2,d4 * for three objects 

move #114 p ctrl0 t opcode “ rsrc_objfix 

move #1 , ctrl 1 * 1 intint 

move #1, Ctrl 2 * 1 intout 

move #l,ctrl3 * 1 addrin 

move. 1 #tree p addrin * pass tree address 

fix loop: 

move d4 p aintin * use loop index for object number 

Jsr aes 

dbra d4 p fixloop t decrement, and do again if not done 


>>> Draw the objects 


#42,ctrl0 * opcode “ objc_draw 

#6, ctrl 1 t 6 intin’s 

#l,aintin+2 t draw down one level 

workx p aintin+4 * set clip x p y p w p h 
worky, aintin+6 
workw, aintin+B 
workh, aintin+10 


ttt Wait for button press 


#21 , ctrl0 
#3, Ctrl 1 
#5, ctrl 2 
#0, Ctrl 3 

#1, aintin 
#1 , aintin+2 
#1, aintin+4 


* opcode “ evnt_button 


t 1 click, left button only 


ttt See if button pressed while mouse was over EXIT object 


#43,ctrl0 
#4, Ctrl 1 
#l,ctrl2 
#1 ,ctrl3 


t opcode « objc_find 


#0, aintin t start searching at root 

aintout+2, aintin+4 * use mouse x and y for position 
aintout +4, aintin+6 


#1, aintout 
loop 


t object 1 found? 

* if not, check again 


ttt Storage space and data constants 
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• data 

• even 



wdwtitl i 
wdwinfos 
wdwctrl i 
ex i tetri 
puahstr * 


.dc.b 'Object Example’ ,0 * text of window title 

•dc.b ' ',0 * text of window info line 

•dc.w 1 * window control flag 

.dc.b ' EXIT’ , 0 

.dc.b 'Push Button to Exit*,0 


trees .dc.l *FFFF0001, *00020014, *00000010, *00021100 

.dc.l *00060005, *0016000A 
objcli .dc.l *0002FFFF , *FFFF001A, *00070000 

.dc.l exitstr 

.dc.l *00000006, *00080001 
objc2t .dc.l *0000FFFF , *FFFF001C, *00200000 

.dc.l pushstr 

.dc.l *00010002, *00150001 


• end 



□ 

n 

□ 

n 

n 
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Building an object tree by calculating the data necessary 
for each field of each structure in the array can be a long and 
tedious process. Each object requires 11 pieces of data. One of 
those is an obspec field, which may be a pointer to another 
data structure such as an ICONBLK which requires another 14 
items of information, two of which are pointers to image data 
arrays. This means that just one object can have a large quan- 
tity of data associated with it. And GEM programs don't just 
use one or two objects; they use dozens. Alerts, dialog boxes, 
menus — all are built of many, many objects. 

There are other problems with building objects out of data 
as well. For one thing, it's difficult to picture the size and rela- 
tionship of objects based on mere numbers. If the object 
doesn't look quite right, you've got to change the numbers 
and recompile to try a new combination. Moreover, as you've 
seen from the example program at the end of the previous 
chapter, you have to change the size and position fields for 
each object based on the current display resolution mode. Fi- 
nally, you have to calculate all the links that define their vari- 
ous parent-child relationships. 

Because objects are an integral part of GEM, and because 
they're so difficult to build from data, Digital Research devel- 
oped a system which can create object data. The system makes 
use of Digital Research's Resource Construction Set or a similar 
program. The Resource Construction Set is one of the best fea- 
tures of GEM. It takes the effort out of creating objects, and it 
allows you to position them relative to one another, change 
their parent-child relationships, enter text, and set the various 
attribute flags and object state flags for each object. 

Once you've created the object data with the program, 
you may save it to a resource file. This is a data file ending 
with the .RSC extender. For instance, STBASIC.RSC is the re- 
source file for the STBASIC.PRG program. When the resource 
file is created, the AES Resource Library routines enable your 
program to load the file, create the object structure data array 
from the information loaded, and find the addresses of indi- 
vidual object trees within that array. 
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Using resource files and a resource construction program 
has several fringe benefits besides making the object creation 
process quick and easy. First, it helps make the program more 
portable, both to other machines (such as the IBM PC) and 
within the various display resolution modes of the ST itself. 

As you'll see later, size and position information are stored 
within resources as character positions and are translated to 
display-specific figures automatically when the resource is 
loaded, much as was done manually in the example program 
in the last chapter. 

Another advantage is that the programmer can experi- 
ment with the size, placement, and characteristics of objects 
without having to recompile each time. All you have to do is 
edit the resource file and run the program to see how the 
changes work. 

Finally, the use of resource files makes it easy to create 
foreign-language versions of your program without recompil- 
ing. In fact, since the user can edit the resource file, the lan- 
guage in menus, dialog boxes, and alerts may be changed 
without any need for programming experience. This makes it 
possible for the program to be customized by the user. For 
these reasons, it's generally preferable to use resource files, 
even if for some reason you think it would be more conven- 
ient to create the object trees within the source code of the 
program itself. 

Resource Construction Programs 

Not every C compiler or assembler for the ST comes with a 
resource construction program, but no GEM programmer 
should be without one. 

The original Resource Construction Set (RCS) is included 
with the ST Developers Kit available from Atari, along with 
the Alcyon C compiler. The Megamax C compiler package in- 
cludes the Megamax Resource Construction Program (MMRCP). 

If you aren't using either of those development systems, 
Kuma Computers Ltd. market a separate resource construction 
program called K-Resource (KRSC), which can be used with any 
compiler or assembler. Each of these programs has slightly dif- 
ferent features. For example, KRSC and MMRCP both have 
built-in icon image editors, while the RCS does not. However, 
RCS and MMRCP both allow the user to load image data that 
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was created using other programs such as Icon Editor, Profes- 
sional Icon Editor, or Degas Elite, while KRSC does not. Under 
most circumstances, however, the differences between these 
programs is not significant. All of them perform very well at 
the basic task of constructing a resource file. 

To build a resource with one of these programs, open a 
resource window, and drag one of several different tree icons 
onto the window. These icons represent various types of ob- 
ject trees, such as menus or dialogs. 

The distinctions among types of object trees are strictly for 
the purposes of the resource construction program itself; no 
actual difference exists in the object structure of these trees. 

But such distinctions can help make the resource programs 
more effective. For example, when you select a menu tree, the 
program presents a prepared template of text objects arranged 
as in a typical menu, and the program restricts your selection 
to the type of text objects found within menus. The dialog tree 
can contain any object, but all objects are positioned so that 
their borders are aligned with even text character positions. 
The free or panel tree can contain any object at any pixel 
position. 

The various resource programs also allow you to edit alert 
strings, as well as free text strings and free images (those not 
contained within an object tree). 

When you drag a tree icon to the resource window, you 
create the root object for that tree (usually a G_BOX with an 
outlined border). To add children to the tree, you drag icons 
representing the various object types to a position in which 
they're completely enclosed by the root object. 

You may create children for these objects also, by drag- 
ging additional icons into their rectangles. Once you've added 
these objects to the tree, edit them as you see fit. You can drag 
them to a new position with the mouse, change their size by 
dragging their lower right hand comer, or edit their attribute 
and flags. Simply double-click on the object to open a dialog 
box. From that dialog box you can set or reset each flag indi- 
vidually. (In RCS version 2, you highlight the icon by clicking 
on it and then select the appropriate flags from pop-up menus 
located on a control panel.) This allows you to experiment 
with the size, placement, and attributes of the objects 
interactively, immediately viewing any changes you make. 
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When you're finished with one object tree, you can add 
more trees until you create all the objects used in your pro- 
gram. When you're satisfied with the results, you may save 
the resource file. In addition, if you've created names for the 
various objects, the program will save those in a separate file 
(for future editing sessions), and it will also save a header file 
containing macro definitions which match the names to the 
corresponding object numbers. The Resource Construction Set 
also allows you to save a file containing C language defini- 
tions for all of the objects and their associated data structures. 


n 

n 

n 




Structure of Resource Files 

Many of the fields included in object structures contain the ab- 
solute memory addresses of other data structures. But it's im- 
possible to know in advance the absolute memory address at 
which the resource file will be loaded, because that depends 
on the program size and which desk accessory programs and 
fonts are loaded. Therefore, in addition to the object structure 
data, and associated data structures, the resource file must also 
contain information that allows the AES to patch in the abso- 
lute addresses where necessary. This information is contained 
in the resource header, a data structure located at the very be- 
ginning of each resource file. This structure consists of an ar- 
ray of words containing the size of the other data structures, 
and their offsets within the resource file. Its C language defini- 


tion is 
int rsh_vrsn 

/* version number */ 


int rsh_object 

/* object block offset */ 


int rsh— tedinfo 

/* TEDINFO block offset */ 


int rsh—iconblk 

/* ICONBLK block offset */ 

R 

int rsh_ bitblk 

/* BITBLK block offset */ 

int rsh_frstr 

/* Free String block offset */ 

int rsh string 

/* String block offset */ 


int rsh— imdata 

/* image data block offset */ 

/* free image data block offset */ 

rn 

int rsh— frimg 

i, ! 

int rsh_ trindex 

/* tree index block offset */ 


int rsh— nobs 

/* number of objects */ 

n 

int rsh— ntree 

/* number of trees */ 

int rsh— nted 

/* number of TEDINFOs */ 

int rsh_ nib 

/* number of ICONBLKs •/ 

n 

int rsh_ nbb 

/* number of BITBLKs */ 

int rsh— nstring 

/* number of strings */ 

int rsh— nimages 

/* number of images */ 

n 

int rsh— rssize 

/* total size of the resource, in bytes */ 
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Following the resource header are the actual data arrays 
that make up the objects. First comes an array of strings, fol- 
lowed by an array of BITBLKs, an array of image data, an ar- 
ray of ICONBLKs, an array of TEDINFOs, and finally the 
array of OBJECTS. 

There are important differences between the data arrays 
stored in the resource file and those stored in the actual object 
array used by the AES Object Library routines. 

First, as noted above, the resource file doesn't contain the 
actual pointers used by the ob__spec field or other data struc- 
tures. Instead, these fields contain an index number which in- 
dicates the position of the desired data structure within its 
array. For example, the ob_spec field of a G_STRING con- 
tains the index number of the desired string within the string 
data array instead of the address of that string. 

Another difference is that screen x, y, width, and height 
values are stored in character units rather than pixel units. For 
example, if a G_BOX starts at position (24,32) and each char- 
acter is eight pixels high and eight pixels wide, the position 
stored in the resource is (3,4). This allows the AES to draw the 
object to scale, regardless of the screen display mode in effect 
at load time (assuming an 80 X 25 character display). If the 
object wasn't created on a character boundary, the low byte of 
each rectangle word contains the closest character position, 
while the high byte contains the number of pixels left over. 

The last data structure in the resource file is another one 
used by the AES when loading the font. This structure is 
called the Tree Index, and it contains the index number of 
each tree's root object in the object array. This allows the AES 
to find the starting address of each object tree in the object 
array. 

Loading a Resource 

In order to use the object trees stored in a resource file, your 
program must first load the resource. The AES provides a spe- 
cial Library routine for just this purpose, called rsrc—load( ). 
The calling sequence for this function is 

int status 

char *filename; 

status = rsrc_load(filename); 

where filename is a pointer to a null-terminated string that 
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contains the name of the resource file. This name is usually 
the same as that of the application, only with an extender of 
.RSC instead of .PRG. For example, RCS.RSC is the resource 
file for the Resource Construction Set program (filename 
RCS.PRG). 

If you don't specify a directory path, GEMDOS will look 
for the the resource file in the same directory as the applica- 
tion, which is the usual state of affairs. If the rsrc_load( ) rou- 
tine is unable to find the resource file or is unable to load it 
properly for any other reason, a value of 0 is returned in the 
status variable. Your program will want to check this variable 
after attempting a resource load, since you'll want to notify 
the user with an alert box and terminate the program at once 
if the resource file didn't load properly. 

When the AES loads a resource file, it finds the size of the 
file, allocates enough free memory to hold it, and then reads 
the contents of the file into the allocated space. 

Next, the AES changes the data structures that were 
loaded into memory. It converts the size and position values 
stored in character units back into pixel units, based on the 
current default character size. It replaces the array offset val- 
ues in the OBJECT, TEDINFO, INCONBLK, and BITBLK struc- 
tures with actual address pointers. It replaces the array offset 
values in the Tree Index with actual address pointers to the 
beginning of each object tree. Then, it stores the address of the 
Tree Index array in the ap—ptree field of the application's 
Global data array. 

Since the rsrc_load( ) process allocates some of the com- 
puter's free memory, you should always remember to give 
that memory back when you end your program. And though 
your program will only load one resource file in most cases, if 
you want to load more than one, you must unload the first 
before loading the second. In either case, the call you use is 
rsrc—free( ): 

int status; 

status = rsrc_free( ); 

Once you've loaded a resource file, you can find out the 
addresses of the various data structures it contains by using 
the rsrc—gaddri ) Library call. The syntax for this call is 

int status, type, index; 
long address; 

status = rsrc_gaddr(type, index, &address); 
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where type specifies the type of data structure, index gives the po- 
sition within the data array, and address is the variable which 
holds the address to be placed in the data structure. The types of 
data structures whose addresses you may find with this function, 
and the macro names assigned them in the GEMDEFS.H header 
file, are as follows: 


Type 


mber 

Macro Name 

Data Structure 

0 

R_TREE 

Object tree 

1 

R-OBJECT 

OBJECT 

2 

R-TEDINFO 

TEDINFO 

3 

R—ICONBLK 

ICONBLK 

4 

R—BITBLK 

BITBLK 

5 

R_STRING 

Pointer to free strings 

6 

R—IMAGEDATA 

Pointer to free image data 

7 

R—OBSPEC 

Ob_spec field of OBJECT 

8 

R-TEPTEXT 

Te_ptext field of TEDINFO 

9 

R—TEPTMPLT 

Te_ptmplt field of TEDINFO 

10 

R—TEPVALID 

Te_pvalid field of TEDINFO 

11 

R—IBPMASK 

Ib_pmask field of ICONBLK 

12 

R—IBPDATA 

Ib_pdata field of ICONBLK 

13 

R—IBPTEXT 

Ib_ptext field of ICONBLK 

14 

R_BIPDATA 

Bi_pdata field of BITBLK 

15 

R—FRSTR 

Ad_frstr — the address of a pointer to a 



free string 

16 

R—FRIMG 

Ad_frimg — the address of a pointer to 



a free image 


In practice, you'll be using rsrc_gaddr( ) most often for 
data structure type R—TREE, the object tree. Once you have 
the address of the object tree, you can use the object index 
numbers to access the individual objects. 

Another type that you may use is R—STRING, which can 
be used to get a pointer to an alert string. Alert strings are 
stored as free strings by the resource construction programs. 
The other data structure types are there primarily for the AES, 
which uses them when it fixes pointers in those data struc- 
tures at resource load time. When you're using rsrc_gaddr( ), 
remember that the input value &address is a pointer to a long 
value (which itself may be a pointer). So if you substitute a 
pointer for the long value address, you still must use a pointer 
to that pointer for the input value as shown below: 

OBJECT *tree; 

rsrc_gaddr(R_TREE, MENUTREE, &tree); 
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Two Resource Library functions remain to be discussed. 
Though these functions are used primarily by the AES during 
the resource load process, you may find use for them in your 
applications. The first is rsrc—objfix( ), and it's used to convert 
an object's position and size values from character units to 
pixels. The syntax for this function call is 

int status, object; 

struct object tree[ ]; 

status = rsrc_obfix(tree, object); 


where tree is a pointer to the array of object structures, and 
object is the index number of the object whose position and 
size is to be converted. While this function is mostly used by 
the AES when it loads a resource file, it could have been used 
in the example in the previous chapter where an object was 
created out of initialized data structures. Here is how the pro- 
gram could have been modified to take advantage of this func- 
tion. This is the section of the program where the position and 
size of the objects were fixed: 


for (x=0;x<3;x++) /* fix object x, y, width, and height */ 


tree 

tree 

tree 

tree 


xj 

x] 

x; 

x 


|.ob_x *= cellw; 
j.ob_y *= cellh; 
|.ob_width *= cellw; 
|.ob_height *= cellh; 


} 


to this: 


for (x=0;x<3;x+ +) /* fix object x, y, width, and height */ 
rsrc_objfix(tree, x); 

In fact, that's just what was done in the machine language 
version of the example. 

The final call is used to store the address of a data struc- 
ture array element in memory. It's called rsrcsaddr, and its 
calling sequence is 

int status, type, index; 
long address; 

status = rsrc_ saddr(type, index, address); 

where type specifies the type of data structure, index gives the 
position within the data array, and address is the variable 
which holds the address to be placed in the data structure. 
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This function is used by the AES when it corrects the address 
pointers at resource load time, but there are instances when 
you may want to use it yourself in a program. 

Though resource files are made to be as independent of 
the display resolution as possible, there are some situations 
where objects may not work equally well in all resolutions. 

The first is when using the low-resolution display mode. 
The resource construction programs are designed to run in me- 
dium- or high-resolution modes, so most resource files are 
built on the assumption that an 80 X 25 character display will 
be used. If this isn't the case, parts of large object trees might 
be lost off the edge of the screen. 

The second area of possible incompatibility concerns the 
aspect ratio of the display. Though objects are lined up by 
character positions, the actual image data of G—IMAGE or 
G—ICON object consists of pixels. If the aspect ratio of the 
display is different from the one on which it was created, the 
icons and images may not look right and may not be located 
in the right spot. For example, the Desktop program icons for 
disks, files, and folders look fine in high- or low-resolution 
modes, but in medium-resolution they appear to be tall and 
skinny. 

There are several ways to deal with this problem. First, 
you can try to make your resource display-independent when 
you create it, by keeping object widths smaller than forty 
characters, and using compromise images that are a little 
shorter and fatter in high resolution than you'd normally 
make them, and a little taller and skinnier in medium 
resolution. 

The second approach is to create separate resource files 
for the different resolutions. To some extent, this goes against 
the basic philosophy of compatibility behind the resource files. 

A third alternative is to place extra image and icon data in 
the resource and patch the appropriate data into the data struc- 
tures whenever the program comes up in a display resolution 
mode for which the object trees weren't designed. In this last 
case you might find the rsrc_gaddr( ) and rsrc__saddr( ) calls 
handy. You can use rsrc_gaddr( ) to find the addresses of the 
alternate data structures and rsrc_saddr( ) to patch them into 
the existing ones. 
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Menus 

One of GEM's most helpful features is its system of drop- 
down menus. These menus are composed of objects whose 
tree is usually loaded as part of the resource file. Once the 
application installs the menu, the menu titles — which display 
the broad categories of selections available — appear in the 
menu bar at the top of the screen. 

When the user moves the mouse pointer over one of 
these titles, the Screen Manager saves the old screen back- 
ground in the menu buffer and draws a box beneath the title. 
This box contains one or more menu items, which represent 
program options that the user may select. 

As the user moves the mouse pointer over a selectable 
item, its text is drawn in reverse video to highlight it. The user 
can click the mouse button over one of these highlighted items 
to pick it. When this happens, the Screen Manager restores the 
background display from the menu buffer and sends a mes- 
sage to the application telling it which menu title and menu 
item were selected. The title belonging to the item you se- 
lected is left highlighted while your program handles the mes- 
sage. If the user decides not to select a menu item, he or she 
may get rid of the menu either by replacing it with another or 
by moving the mouse pointer off the menu bar entirely and 
clicking the left mouse button. 

All of the data for a menu is contained in a normal GEM 
object tree. But since the AES Screen Manager does so much 
autonomous manipulation of menus, this object tree must fol- 
low a set format. 

Since the menu system uses objects that can be located in 
the menu bar or anywhere else on screen, the root object of 
the menu is a G—BOX that covers the entire display area of 
the screen. This root object has exactly two children, whose 
rectangles cover the root object completely. The first, called 
the BAR, is a G_BOX that covers the whole menu bar at the 
top of the screen. The second, called the SCREEN, is a 
G—IBOX that covers the rest of the display area, excluding the 
menu bar. 

The BAR and the ACTIVE. The BAR is 80 characters 
wide and is one character plus two pixels high. It contains ex- 
actly one child, a G_IBOX called the ACTIVE. The ACTIVE 
covers only the portion of the menu bar that actually contains 
menu title objects. It takes its name from the fact that the 
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Screen Manager activates a menu whenever the mouse pointer 
enters its rectangle. The ACTIVE has as its offspring the vari- 
ous G—TITLE objects that represent the menu titles. These ob- 
jects should line up side to side and completely cover the 
ACTIVE. 

The SCREEN. The other child of the root object, the 
SCREEN, is the parent of the box objects which contain the 
drop-down menus that appear under the menu titles. Each 
drop-down is a separate G—BOX child of the SCREEN. No 
single drop-down box can be larger than one quarter of the 
screen display in size, since that's the size of the offscreen 
buffer where the AES temporarily stores what's in the screen 
display behind the menu. The drop-down boxes each contain 
a number of objects, usually G_STRINGS, that represent the 
individual menu items. These objects should completely cover 
the drop-down's rectangle. 

Because of the rigid hierarchy requirements of menu ob- 
ject trees, it would be extremely difficult to construct one with- 
out using a resource construction program. 

When you open a menu-type tree with a resource con- 
struction program, it automatically creates the root object, the 
BAR, the SCREEN, the ACTIVE, and a couple of default menu 
titles containing appropriate menu items. Whenever you create 
a new menu tide the program changes the size of the AC- 
TIVE, moves the new title so that it's adjacent to previous 
ones, and creates the drop-down box with space for a single 
menu item. 

In return for this convenience, however, these programs 
enforce some restrictions. Most only allow you to use 
G_STRING-type objects for menu items. While G_STRINGs 
are the preferred choice for this task, because it's easy for the 
AES to draw them quickly, there are some cases where you 
might prefer to use box-type objects, or even icons. 

In order to add non-G_STRING objects as menu items 
with the resource construction programs, you must first create 
the menu tree, then close it, and change its tree type from 
menu to dialog. At that point, you can enlarge the drop-down 
boxes and add any object that you wish. Each object, how- 
ever, should still stretch across the entire width of the drop- 
down box. If you want to place two or more siblings side by 
side on a line, make sure that you cover them with another 
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sibling that occupies the whole line, so that they all get se- 
lected at the same time when that menu item is chosen. If any 
of the drop-down box is left exposed, the whole box will be 
inverted when the user moves the mouse over that part. 

In a dialog tree, you'll find that all of the objects are 
drawn at once, making it difficult to get at some of the over- 
lapping siblings. By setting the HIDETREE attribute flag, you 
should be able to temporarily remove those that are in your 
way and then reveal them when you're done. 

Once you've finished editing the tree, you should be able 
to close it and to change it back to a menu tree. If you've 
obeyed the rules, the resource construction program should let 
you make the change. 

There are certain menu conventions which GEM pro- 
grams should follow, in order to promote uniformity. The first 
menu title is customarily set to DESK. The DESK drop-down 
box must contain exactly eight menu items. The first is usually 
titled About Program . . . , where Program is filled in with the 
name of the application. Note the three dots at the end of this 
item. This is another GEM convention, which tells the user 
that selecting this item leads to a dialog (in this case, the dia- 
log box which displays the program credits). The next item is 
a line of faint dashes, created by setting the DISABLED flag. 
This line is a conventional device called a separator bar, which 
sets off one group of menu options from another. The other 
six objects are dummy strings which the AES fills in with the 
names of desk accessories that have registered their menu 
entries. 

The next menu title should be FILE. The drop-down for 
this title should contain entries like New, Open . . . , Save, 
Save As ... , and Quit. Some of these items may contain a 
symbol next to the text, such as Open . . . A 0. This shows the 
user that there are keyboard equivalents to this menu item. In 
the example shown, the user could hold down the Control key 
and press the letter O, and it would have the same effect as if 
the Open . . . item had been selected from the menu. 

The next title to use, if appropriate, is EDIT. This contains 
items such as Cut, Copy, Paste, and Delete. From there on, 
the menu title selection is up to you. One thing that you 
should keep in mind when creating menus, however, is to 
keep them short. If you find that you need more than eight or 
nine menu items, you may want to consider going to a dialog 
box instead of a menu. 
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Using Menus 

Once you've created your menu tree with the resource con- 
struction program of your choice, the next step is installing it 
from your program. After you've loaded the resource file with 
rsrc—load( ), the next step is to retrieve the address of the menu 
tree with the rsrc—gaddk ) call: 

long menuaddr; 

rsrc_ gaddr(R_ TREE, MENUTREE, &menuaddr); 

R—TREE is a macro name defined in GEMDEFS.H, and 
MENUTREE is a macro name for the root object of your menu 
tree, defined in the .H file created by the resource construction 
program. When you've got the address of the menu tree, 
you're ready to tell the AES to install your menu. You do this 
using the menu—bar( ) call, whose syntax is as follows: 

int status, showflag; 

OBJECT *tree; 

status = menu_bar(tree, showflag); 

where tree is a pointer to an object tree (in the example above, 
you would use &menuaddr for that pointer). Showflag indicates 
whether you want to draw the menu bar or erase it. When 
you wish to install the menu bar, set showflag to 1. At the end 
of your program, before calling appl—exit, you should erase the 
menu bar by calling menu_bar( ) once again, only this time, 
with showflag set to 0. 

Once you've called menu_bar( ), the AES draws your 
menu bar at the top of the screen and begins to handle user 
interaction with the menus. When the user moves the mouse 
pointer to the ACTIVE, the AES drops down the proper menu. 
When the user selects a menu item, the AES sends your pro- 
gram message number 10, MN—SELECTED. The format for 
this message is 

Word 

Number Contents 

0 10 (MN_SELECTED), a menu item was selected by the 

user 

3 The object number of the menu title that was selected 

4 The object number of the menu item that was selected 

When your program receives this message (via an 
evnt— multi or evnt—. message call), you'll generally check word 
4 of the message buffer to see what item was selected and 
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take the appropriate action. While you are performing what- 
ever task the user has selected, the AES leaves the menu title 
display highlighted to show that the program is busy pro- 
cessing the menu request. When you've finished, you must 
change the title back to its normal video display with the 
menu—tnormal function. The calling format for this function is 

int status, title, setting; 

OBJECT *tree; 

status = menu— tnormahtree, title, setting); 

where tree is a pointer to the menu object tree, title is the ob- 
ject number of the title, and setting is a flag indicating how 
you want that title displayed. If setting contains a value of 1, 
the title will be drawn in normal video. If setting is 0, the title 
will be highlighted in reverse video. Under normal circum- 
stances you'll be using word 3 of the message buffer for the ti- 
tle object number and a setting of 1. 

Program 5-1 demonstrates some simple menu handling. It 
sets up a menu with three titles and four selectable items. The 
DESK menu contains one item: About Menul. . . . The FILE 
menu contains one item: Quit ~C. The DRAW menu contains 
two items: Pattern 1 [FI] and Pattern 2 [F2]. The About item 
on the DESK menu is used to display an alert box (those will 
be covered in more detail in the next chapter), the two DRAW 
items draw patterned ellipses in the program window, and the 
Quit item is used to exit the program. Because this is a simpli- 
fied example, the handle— msg( ) routine only deals with menu 
messages. In an actual application, your program would have 
to deal with all of the window messages as well. 

Program 5-1. menul. c Program 

/*t**«**t*t****tt***t***»*********t**t*ttt*ttttt***ttt****t*****t**/ 


/* */ 

ft MENU1.C — Demonstrates handling of simple menus, tf 

ft with keyboard equivalents. tf 

ft tf 


fttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttf 

tidefine APP_INFO " « 

tidefine APP NAME "Menu Ex ample 1" 

tidefine WDW.CTRLS <NAME) 

tidefine MCUSE^OFF graf_mouse (256, & dummy) 
tide-fine MQUSE_QN graf _mouse<257, Stdummy) 

tide-fine CTRLQ 0x1011 ft keycode for CTRL-Q key combo */ 

tidefine FI KEY 0x3B00 ft keycode -for function key 1 tf 

tidefine F2KEY 0x3C00 /* keycode for function key 2 tf 

tiinclude "aesshel 1 . c" 

tiinclude "menul. h” /* include file from RCS */ 
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U 

U 

u 


LJ 

LJ 

u 

u 

u 


int dummy; 

OBJECT Smenutree; 
char talert; 

demoO 

C 


int event i done = 0; 
int key, msgC8J; 

if ( !rsrc_load ( "MENUl .RSC" ) ) ft Load resource -file tf 

f orm_alert (3, M E0D [Fatal ErrorICan't find MENUl. RSC f ile! 3CAbort3 H > ; 
return(0>; /* Abort if it's not there */ 

> 


ft get address of menu tree and alert string */ 
rsrc_gaddr (R_TREE, MENUTREE, fcmenutree)j 
rsrc_gaddr (R_STR1NB, ABT ALERT, fcalert); 


MOUSE_QFF; 

menu.bar (menutree, 1 ) ; 
MOUSE_DNj 


ft Hide the mouse pointer */ 
ft Show the menu bar */ 

/t Show the mouse pointer t / 


vsf_interior (handle, 2) | /* Set Fill Pattern for Ellipse tf 

ft Main Program Loop */ 

while < ! done) ft until user selects "Quit** item t/ 

< /* check menus and keyboard tf 

event = evnt_mul t i <MU_MESAB I MU__KEYBD , 

0,0,0, ft evnt_button tf 

0,0, 0,0,0, /t evnt_mousel */ 

0,0, 0,0,0, /t evnt_mouse2 tf 

&msg, /* evnt_mesg t/ 

0,0, /* evnt_timer */ 

Scdummy, Stdummy, /* mouse x,y tf 

Scdummy, ft mouse button tf 

Stdummy , /* shift keys tf 

fickey, ft evnt_keyboard tf 

Stdummy); ft number of clicks */ 


if (event St MU_MESAG) /* if we get 
done = handle_msg (msg) ; 


a message, handle it tf 


if (event St MU_KEYBD) ft if key, check for equivalents */ 
done = handle_key (key) ; 

> ft end of main WHILE loop tf 

menu_bar (menutree, 0) ; ft Remove the menu bar tf 

y ft end of DEMO function */ 


ft Message Handler routine — only handles menu messages tf 
ft (yours should also handle redraws, window topping, etc. tf 

handle_msg (msg) 
int msgC83; 

C 


int done=0; 


switch (msgl!03) 

C 

case MN_SELECTEDs 
switch (msgC43) 
< 


ft check message type tf 

ft if menu message type tf 
ft check menu item tf 


145 




case ABQTITEM: /% if About... display alert */ 

f orm_alert (0, alert) ; 
break; 

case PATlITEMx /* draw Pattern It/ 
draw (7, 2) ; 
break; 

case PAT2ITEM: /% draw Pattern 2 */ 

draw(5 v 3) ; 
break; 

case QUITITEM: /* Quit */ 

done = 1; 
break; 
dof aulti 
break; 

> /* end of switch on menu item %/ 

menu_tnormal (menutree, msgC33, 1); ft set menu to normal */ 
break; 

default: 

break; 

}/t end of switch on message type t/ 

return (done) ; /* report done status */ 

> 

/* Keyboard Handler routine — checks for keyboard t/ 

/* equivalents of menu selections */ 

handle_key (key) 
int key; 

int done = 0; 

switch (key) /* check key code tf 

< 

case F1KEY: /* draw Pattern 1 */ 

draw (7 V 2) ; 
break; 

cat* F2KEY: /* draw Pattern 2 */ 

draw (5,3) ; 
break; 

case CTRLQx /* Quit t/ 

done ** 1; 
break; 
default: 
break; 

> ft end of switch on key t/ 
return (done) ; 

> 

ft Ellipse Drawing Routine */ 

draw (pattern, color) 
int pattern, color; 

vsf_style (handle, pattern) ; 
vsf _col or (handl e, col or ) ; 

MDUSE_QFF; /t Hide the mouse pointer tf 

v_el 1 ipse (handle, work. g_x+work.g_w/2, wor k. g_y+work. g_h/2, 
work.g_w/2, work.g_h/2); 

MOUSEJBN; /* Show the mouse pointer */ 

> 

/* tttttttttttttttttt End of Menul.c tttttttttttttt t/ 


n 

n 

n 


n 

n 

n 

n 

n 
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In order to run this program, you must first create a re- 
source file called MENU1.RSC. If you have a resource con- 
struction program, you'll need to create two object trees. The 
first is a menu tree with the C macro name MENUTREE. This 
menu has three titles. To the default DESK and FILE titles add 
a DRAW title. Under the DESK menu, edit the first item's 
string to read About Menul . . . and give it the C macro name 
ABOTITEM. Edit the item under the FILE menu to read Quit 
*Q and give it the name QUITITEM. Next, add two items un- 
der the DRAW menu. The first reads Pattern 1 [FI] and has 
the name PAT1ITEM. The second reads Pattern 2 [F2] and has 
the name PAT2ITEM. The second object tree is an alert string 
called ABTALERT. Drag four strings to the alert window. The 
first line reads Menu demo with multi-object, the second reads 
items and keyboard equivalents, and the third reads Select 
" Quit " to end. The fourth line is made up of dashes. The string 
in the button should be edited to read I’ll remember that. 

If you don't have a resource construction program, you 
should get one without further delay, but in the meantime, 
you'll be able to build the resource file needed for this ex- 
ample by running the RSCBUILD program in Appendix C. 

The resource file that we created for this program was a 
bit fancier than the one described above. The menu items Pat- 
tern 1 and Pattern 2 each include a colored G_BOX which dis- 
plays the pattern fill. To create this kind of a menu item, you 
must first change the type of the tree from menu to dialog in 
your resource construction program. 

When you display this tree, all the drop-downs will be 
visible. Get a hold of the drop-down box for DRAW by hold- 
ing down the Control key and holding down the mouse but- 
ton in the lower right comer of the box. This selects the parent 
object. Drag the box to the right so that you make some room 
for a G—BOX. At this point, it's probably a good idea to move 
the second menu item to the clipboard, temporarily. Next, add 
a G—BOX that completely covers the space to the right of the 
G_STRING on the top line. Make it foreground color 2, fill 
style 6, with an outside border of one pixel. Next, move a 
G_ IBOX to the second line and size it so that it covers the en- 
tire menu line. Edit it to remove the border and move it over 
the top menu line. If your editor tells you that the G—IBOX 
now covers its two siblings, and asks if you want to make it 
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their parent, answer "No." You want the three objects to re- 
main siblings, so that when the user selects the IBOX, all will 
be highlighted. Repeat the process with the second menu item 
(its G—BOX has a foreground color of 2 and a fill pattern of 5), 
and you've got a menu with words and pictures on the same 
line. 

Once you've set up your menu, there are a number of 
ways you may modify it. One way you can change a menu 
once your program is running is to disable or reenable one or 
more menu items. Disabling a menu item signals the user that 
a choice is temporarily inappropriate. For example, if the user 
starts a new project which hasn't yet been named, you might 
not want to allow the Save option to be used, forcing the user 
to use Save As ... . And if the user hasn't entered any infor- 
mation since starting the project, you might want to prevent 
the use of either Save or Save As .... To disable a menu, you 
use the menu—ienable( ) function, whose syntax is as follows: 

int status, item, setting; 

OBJECT *tree; 

status = menu— ienable(tree, item, setting); 

where tree is a pointer to the menu tree, item is the object 
number of the menu item to change, and setting is a flag 
which indicates whether you wish to enable or disable that 
menu item. A setting of 0 indicates that you want the menu 
item disabled, while a setting of 1 directs the AES to reenable 
that item. What the menu_ienable( ) call actually does is 
change the DISABLED flag. If you prefer, you may also 
change this by using objc—change( ), or by writing a new value 
directly to the obstate member of the object structure. When 
the DISABLED bit is set, the AES draws the affected menu 
item faintly and won't allow the user to select that item. 

The menu—ienable call normally works for menu items 
only and doesn't work for menu titles. There is, however, an 
undocumented feature in the current version of GEM which 
allows you to disable an entire title. If you call menu_ienable 
with the top bit of object number set to 1, the menu title will 
be drawn faintly, and the AES won't drop down its menu box 
when the user moves the mouse pointer over it. Since this is 
an undocumented feature which may not work reliably, use it 
with caution and don't be surprised if it's changed in future 
versions of the operating system. 
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Some menu selections represent Boolean "on-off" types of 
choices. For example, a text-editing program might allow you 
turn a word-wrapping feature either on or off. If your menu 
item allows the user to toggle this feature from on to off to on 
again, there's got to be some way of knowing what the current 
state of affairs in order to determine whether or not to toggle 
the item. One way of letting the user know is to put a check- 
mark next to the text of the menu item when it's selected and 
to erase it when it's not selected. The menu—icheck function al- 
lows you to either place a checkmark next to the text of a 
menu item or to erase the checkmark. The syntax for this call 
is 

int status, item, setting; 

OBJECT *tree; 

status = menu— icheck(tree, item, setting); 

where tree is a pointer to the menu object tree, item is the ob- 
ject number of the menu item, and setting is a flag indicating 
whether you want to place the checkmark or remove it. A set- 
ting of 1 adds the checkmark, and a setting of 0 removes it. 
Since the checkmark is drawn at the left side of the text box, 
you should always leave one or two blank spaces in front of 
the item's text (this will make the menu look better whether 
or not you use checkmarks). As with menu_ienable( ), 
menu_icheck( ) actually changes the setting of a single bit in 
the ob—State( ) word. In this case, it's the CHECKED flag, and, 
if you prefer, you may change this flag directly as well. 

Another way to indicate the current setting is to change 
the text of the menu item itself. Typically, if the option is on, 
the menu item will read Turn this option off, and when it's off, 
it will read Turn this option on. You can change the text of a 
G_ STRING menu item by using the menu— text call: 

int status, item; 
char *text; 

OBJECT *tree; 

status = menu— text(tree, item, text); 

where tree is a pointer to the menu object tree, item is the ob- 
ject number of the text object to change, and text is a pointer 
to the replacement string. The size of the replacement string 
should be the same as the original one. If it's longer, it may go 
out of the menu box and onto the desktop. If you're planning 
to use replacement strings, include enough space at the end of 
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each menu item so that the drop-down box will be large 
enough to accommodate the longest string. 

Program 5-2 demonstrates how to handle checkmarks, 
disabled menu items, and menu items with alternating text. 

Program 5-2. menu2.c 

/** t *s* tttt* t *********** t ************ t**t**«t**tttt**s*t*t**t*s**t*/ 


/* */ 

/* MENU2.C — Demonstrates handling of check marks, */ 

/* disabled menu items, and alternate text. */ 

/* */ 


/**********»*** *************** «*****>«*»* ********************* tt***/ 

♦♦define APP.INFO “ " 

♦♦define APP.NAME "Menu Example 2" 

♦♦define WDW_CTRLS (NAME) 

♦♦define MOUSE_OFF graf .mouse (256, Sid ummy) 

♦♦define MOUSE ON graf mouse (257, St dummy) 

♦♦define CTRLQ“0 x10U 7* keycode for CTRL-Q key combo */ 

♦♦include “aesshel 1 - c" 

♦♦include "menu2.h M /* include file from RCS */ 

int dummy, key, msgCSI; 

char *alert, tmenuon, *menuoff; 

OBJECT t menutree; 


n 

n 

n 


demo ( ) 
C 


int event, done = 0; 

if ( !rsrc load ( ,, MENU2.RSC , ’> ) /* Load resource file */ 

i 

form.alart (3, " C0KFatal ErrorJCan't find MENU2.RSC f i le! 1 CAbortil") ; 
return(0>j /* Abort if it's not there */ 

> 


/* get address of menu tree, alert and item strings */ 
rare gaddr<R TREE, MENUTREE, fcmenutree) ; 
rsrc_gaddr(R_STRINS, ABT ALERT, Stalert); 
rsrc gaddr(R STRING, ONSTRNG, Stmenuon); 
rsrc”gaddr (R~STRINS, OFFSTRNB, Stmenuoff); 

MOUSE_OFF | /* Hide the mouse pointer */ 

menu.bar (menutree, 1) ; /* Show the menu bar */ 

MOUSE.ON; /* Show the mouse pointer */ 

/* Main Program Loop */ 


while <! done) /* 
C /* 
event =» evnt.multi 


0 , 0 , 0 , 

0 , 0 , 0 , 0 , 0 , 

0 , 0 , 0 , 0 , 0 , 

&msg, 

0 , 0 , 

Stdummy , Stdummy , 
Stdummy, 

Stdummy, 

Sckey, 

Stdummy) | 


/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 


until user selects “Quit 11 item */ 
check menus and keyboard */ 
<MU_MESAS l MU .KEYBD, 
evnt.button */ 
evnt.mousel */ 
evnt_mouse2 */ 
evnt_mesg */ 
evnt_timer */ 
mouse x,y */ 
mouse button */ 
shift keys */ 
evnt .keyboard */ 
number of clicks */ 
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if (event & MU_MESAB> /* if we get a message, handle it */ 
done a handle_msg ( ) ; 

if (event & MU KEYBD) ft if key, check for equivalents */ 
if (key «« CTRLQ) 
done » 1; 

> ft end of main WHILE loop */ 
menu_bar (menutree,0) ; ft Remove the menu bar %/ 

> ft end of DEMO function */ 

ft Message Handler routine — only handles menu messages %/ 
ft (yours should also handle redraws, window topping, etc. */ 

handle_msg(> 

< 


u 

u 





int done=0; 


switch (msgC03) 

C 

case MN.SELECTED: 
switch (msgC43) 
<. 


ft check message type tf 

ft if menu message type tf 
ft check menu item tf 


case ABOTITEMs ft if About... display alert */ 
form_alert <0, alert); 
break; 

case CHEKITEM: ft Toggle Checkmark tf 

if ( menutreeC CHEKITEM 3. ob state b CHECKED) 


menu_i check (menutree, CHEKITEM, 0); 
text ("Check Mark is now turned QFF",i>; 
> 

else 

C 

manu.i choc k (menutree, CHEKITEM, 1); 
text ("Check Mark is now turned ON' 1 , 2); 

> 

break; 


case TOBLITEM: ft draw Pattern 2 tf 

if (menutreeCABLEITEMl.ob state & DISABLED) 

C 

menu^i enable (menutree, ABLEITEM, 1); 
menu_text (menutree, TOBLITEM, menuoff); 
text7 u Menu Item is now turned ON”, 2); 

> 

else 

c 

menu_i enable (menutree, ABLEITEM, 0); 
menu_text (menutree, TOBLITEM, menuon) ; 
text ("Menu Item is now turned QFF",1); 

> 

break; 

case ABLEITEM: ft draw Pattern 2 */ 

text ("Thanks for turning me on M ,l); 
break; 

case QUIT ITEM: /* Quit */ 

done » 1; 
break; 
default: 
break ; 

> /* end of switch on menu item tf 

menu_tnormal (menutree, msgC33, 1); / * set menu to normal tf 
break; 
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default! 
break | 

y/t end of switch on message type tf 

return (done) ; ft report done status */ 


/* Print Text Routine t/ 


text (string, color) 
int col or | 

Char tstring; 

< 

vst.col or (handl e, col or ) } 
MGUSE.OFF; 
clear_rect (Scwork) j 
v gtext (handle, 10$cellw, 
MOUSE _CN; 


/* Hide the mouse pointer %/ 
ft clear the area */ 
20tcellh, string); 
ft Show the mouse pointer tf 


> 

ft ttttttttttttttttttttttttt End of Kenu2.c tttttttttttttttttttt tf 


In order to run this program, you must first create a re- 
source file called MENU2.RSC. If you have a resource con- 
struction program, you'll need to create an object tree, an 
alert, and two free strings. The object tree is is a menu tree 
with the C macro name MENUTREE. This menu has three ti- 
tles. To the default DESK and FILE titles add an OPTION title. 
Under the DESK menu, edit the first item's string to read 
About Menu2 . . . and give it the C macro name ABOTITEM. 
Edit the item under the FILE menu to read Quit A Q and give it 
the name QUITITEM. Next, add four items under the OP- 
TION menu. The first reads Check Mark and has the name 
CHEKITEM. The second is just a gray separator bar. The third 
reads Turn the Next Item ON and has the name TOGLITEM. 
The fourth is a disabled sting that reads Print Message in faint 
letters. The alert string called called ABTALERT has four string 
lines. The first reads Menu demo with check marks, the second 
reads graying, and alternate text, and the third reads Select 
"Quit" to end. The fourth line is made up of dashes. The string 
in the button should be edited to read I'll remember that. You'll 
also have to create two free strings. The first is called 
OFFSTRNG and reads Turn Next Item OFF, while the second 
is called ONSTRNG and reads Turn Next Item ON. If you 
don't have a resource construction program, you'll be able to 
build the resource file needed for this example by running the 
RSCBUILD.C program in Appendix C. 
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Interactive Object 
Handling: 
Forms and the 
File Selector 




The highest level of AES object routines are so 

sophisticated that they're more like large subprograms than 
simple functions. The programs in the Forms and File Selector 
Library perform all the same functions as the sample object 
programs from Chapter 4, and more. They display a set of ob- 
jects (called a form) which is loaded as one of the object trees 
in the resource file. They check for significant AES events and 
handle all of the user's interaction with these objects. Finally, 
when they've detected an event that ends the interaction, they 
report its results to the application. This means that the pro- 
grammer can easily create interactive forms with his or her re- 
source construction program and can let these functions take 
care of the the job of watching for user input. The AES aids 
the user in filling in the blanks and checking the boxes and 
provides the results to the application. 


Forms 

The simplest kind of form is an error box. This is a box object 
which contains an image, a text string, and a button. The im- 
age, which appears at the left side of the box, is that of a stop 
sign. The text string, which appears at the top of the box, 
either contains an explanatory error message or just reads TOS 
error #X, where X is a number that corresponds to a TOS sys- 
tem error. Finally, the button appearing at the bottom of the 
box reads Cancel. This form makes it easy to let the user know 
when a TOS error occurs. When a TOS function returns an er- 
ror number, your program can simply call form—erroii), which 
will display the error message box until the user clicks on the 
Cancel button. The syntax for the form_error call is 

int exitbutn, error; 
exitbutn = form_error(error); 

where error is the error number. Unfortunately, GEM is de- 
signed with IBM PC-DOS error codes in mind, rather than 
GEMDOS error codes returned on the Atari ST computers. 
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Therefore, in order for form_error( ) to print out its error mes- 
sages correctly, you must convert the GEMDOS codes to PC 
DOS codes. This is done by reversing the sign of the code 
from negative to positive and then subtracting 31 (DOS—ERR 
= (— TOS—ERR) — 31). The following chart lists the 
GEMDOS error codes for which form_error( ) prints error- 
specific messages (as opposed to TOS error #X) and gives the 


complete text of those messages. 

GEMDOS PC-DOS 
Error Error 

Error 

Number 

Number 

Error 

form_error( ) Message 

-33 

2 

File not found 

This application can't find 
the folder or file you just 
tried to access. 

-34 

3 

Path not found 

This application can't Find 
the folder or file you just 
tried to access. 

-35 

4 

File-handle pool ex- 
hausted (no File handles 
left) 

This application doesn't 
have room to open an- 
other document. To make 
room, close any document 
that you don't need. 

-36 

5 

Access denied (wrong 
attribute or access'code) 

An item with this name 
already exists in the direc- 
tory, or this item is set to 
Read-only status. 

-39 

8 

Insufficient memory 

There isn't enough mem- 
ory in your computer for 
the application you just 
tried to run. 

-41 

10 

Invalid environment 

There isn't enough mem- 
ory in your computer for 
the application you just 
tried to run. 

-42 

11 

Invalid format 

There isn't enough mem- 
ory in your computer for 
the application you just 
tried to run. 

-46 

15 

Invalid drive specification 

The drive you specified 
does not exist. Check the 


drive's identifier or 
change the drive identifier 
in the DISK INFOR- 
MATION dialog. 
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GEMDOS 

PC-DOS 

Error 

Error 

Number 

Number 

-47 

16 

-49 

18 


Error 

Attempted to remove the 
current directory 

No more files 


Error 

form— error( ) Message 
You cannot delete the 
folder in which you are 
working* 

This application can't find 
the folder or file you just 
tried to access. 


Although GEM provides codes for more than one exit 
button, the current ST version uses only the Cancel button, so 
that a value of 0 is always returned in exitbutn. 

Alerts 

The error form is actually a specialized case of a more versatile 
message display form called the alert. Alert boxes are used to 
inform the user that a situation has arisen in which some im- 
mediate action may be required. Alerts make it easy to present 
to the user a short message and a choice of up to three op- 
tions. A typical use is verifying that the user really wants to 
take some irrevocable action, such as Loading new data will de- 
stroy current data. Do you wish to proceed? [Yes] [No]. Another 
use of the alert would be to inform the user of an error as in 
Data file cannot be loaded [Cancel]. 

The alert box consists of an optional image, up to five 
lines of text, and from one to three exit buttons. To display the 
box, you use the fomi—alert( ) call, whose syntax is 

int exitbutn, default; 
char ‘string; 

exitbutn = form_alert(default, string); 

where default is the number of the default exit button. Since 
there may be up to three exit buttons with which the user may 
close the alert box, the default should be a number in the 
range 1-3. The variable string is a pointer to a specially for- 
matted text string which describes the image (if any), the mes- 
sage text, and the exit buttons. The format for this string is 

"[Icon— number][Message text][Exit button text]" 

This string is separated into three parts, each of which is 
set off by square brackets. The first item, icon_number, is a 
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single numeric digit indicating which image (if any) should be 
displayed at the left side of the alert box. The choices are 


Image 

Number 

Image 

Meaning 

0 

None 


1 

Exclamation point in diamond 

Note 

2 

Question mark in yield-sign triangle 

Wait 

3 

Octagonal stop sign 

Stop 


These images are used to indicate alerts of increasing im- 
portance. The NOTE alert may be used to pass information 
that's only of casual interest to the user, while the STOP alert 
should be reserved for the situation where data may be lost if 
the user proceeds. 

The second set of square brackets holds the text message. 
This message is limited to a maximum of five lines, each of 
which may contain a maximum of 40 characters. The vertical 
bar character ( I ) is used to indicate the start of a new line. For 
example, the string [This is line 1 1 This is line 2 1 This is line 3] 
prints in an alert as 

This is line 1 
This is line 2 
This is line 3 

The final set of square brackets contain the text for the 
exit buttons. A maximum of three exit buttons may be used, 
each of which contains a maximum of 20 characters of text. As 
with the message string, the text for each button is separated 
with a vertical bar character. When the alert concludes, the 
number of the exit button (1, 2, or 3) is returned in the 
exitbutn variable. Note also that when the alert ends, the AES 
automatically restores the screen rectangle it had covered. 

Since the AES stores the screen background in the menu/alert 
buffer, it can use the raster blit functions to replace it without 
intervention from your program. 

There are two ways to generate an alert string. The first is 
to create it using a resource construction program, save it as 
part of the resource file, and then use the rsrc—gaddii ) func- 
tion with the R—STRING type to find its address. The menu 
program examples in the preceding chapter use this method to 
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display the alert boxes for the About . . . menu items. The sec- 
ond way is to simply include the string constant as part of 
your form__alert call, like this: 

form— alert(l, "[2J[ To be or not to be ... I That's a question? I 
j[YES I NO I MAYBE]"); 

This method is used in the menu examples to generate 
the alert that notifies the user that the resource file can't be 
loaded, since you can't very well get this string from the re- 
source file. 

Dialog Boxes 

The final type of form, the dialog box, is much more flexible 
than simple error boxes or alerts. Dialog boxes may contain 
any number of GEM objects of any type. They may be used to 
present a large number of on-off selection buttons, along with 
mutually exclusive radio buttons. They may include neatly for- 
matted text strings into which the user may enter information 
via the keyboard. And, as you will see, with a little work they 
can even contain more sophisticated constructs such as slide 
bars. 

The Form Library routine /orm_do ( ) is used to animate a 
dialog once it's been displayed. In most cases, form_do( ) han- 
dles all the user's interaction with the objects in the dialog. 

For example, if there are any formatted text objects in the dia- 
log (G—FTEXT or G—FBOXTEXT), form_do( ) positions the 
text cursor at the first editable field and handles all the key- 
board input from the user. If the user enters a valid text char- 
acter (one that matches the criteria of the validation string), 
form_do( ) inserts it into the text string. If the user types an 
invalid character, form_do( ) ignores that character. If the user 
types an invalid character that's part of the template, 
form_do( ) moves the cursor to the first space past that tem- 
plate character. For example, if the template string is 

Date: / / , when the user enters a slash, the cursor 

moves to the space following the next slash in the template. 

Form_do( ) also handles a number of cursor and control 
keystrokes. These include the cursor keys. Tab, Shift-Tab, De- 
lete, Backspace, Esc, and Return. 

Left and right cursor keys. These move the text cursor 
backwards or forwards through the text field. 
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Up and down cursor keys. Tab, and Shift-Tab. The 
down-arrow key or Tab key can be used to move the text 
cursor to the next editable text field. The up-arrow key or 
Shift-Tab combination can be used to move to the previous 
text field. The cursor moves to the first open character position 
in the text field. 

Delete and backspace. Delete removes the character to 
the right of the cursor, while the backspace key removes the 
character to the left of the cursor. 

Esc. The Esc key clears all characters from the text field. 

Return. Return selects the first object with the DEFAULT 
flag set in its ob— flags field. This object is highlighted, and the 
form_do( ) ends, returning the object number of the DE- 
FAULT object. If no objects are designated as DEFAULT, 
form_do( ) ignores the Return key. 

The other major task that form_do( ) performs is handling 
selection of objects that have the SELECTABLE flag set in 
their ob_flags field. These objects may be of the type G_BOX, 
G-BOXTEXT, G-BUTTON, or even G—IMAGE or G_ICON. 

To select such an object, the user moves the mouse 
pointer over the object, presses the left mouse button, then re- 
leases it. Form_do( ) checks to see which object the pointer is 
over when the user clicks and selects that object. When an ob- 
ject is selected, it is redrawn in its highlighted form. This 
usually means that the entire object rectangle is inverted, so 
that each pixel of color is changed to its complement. The pro- 
gram may, however, use its own form of highlighting. It can 
do this either by using TOUCHEXIT objects so that the pro- 
gram regains control and can do its own drawing when the 
user clicks on them, or by using G—PROGDEF type objects so 
that the program's own routine is called automatically when 
the object is to be drawn or highlighted. 

As part of its object selection service, form_do( ) handles 
the mutual-exclude feature of objects whose flag settings in- 
clude RBUTTON in their ob_flags field. As explained in 
Chapter 4, these objects, which must all be siblings, deselect 
all others when one is selected. Form_do( ) respects this flag 
and makes sure that only one radio button is selected at a 
time. 

Form_do( ) will continue handling input from the user 
until an exit condition occurs. The most common exit condi- 
tion occurs when the user selects an object that has the EXIT 
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U 

U 

u 






u 

u 

u 


and SELECTABLE flags set in its ob_flags field. Typically, exit 
objects include buttons that read OK or Cancel. If one of these 
objects has its DEFAULT flag set, then the user can exit 
form_do( ) by pressing the Return key. 

Finally, if an object has the TOUCHEXIT flag set, 
form_do( ) will exit as soon as the user moves the mouse 
pointer to the object and presses the button down. This allows 
the programmer to create draggable object types by seizing 
control when the user starts to drag the object. When 
form_do( ) exits, it returns the object number of the object 
whose selection terminated the form_do( ) call. 

There is a set procedure to follow when using form_do( ) 
to animate a dialog. First, load the resource file with the 
rsrc—load( ) call. Next, find the address of the dialog tree with 
the rsrc—gaddr( ) call. Then, use the form—center( ) command to 
center the dialog box on screen. The syntax for this call is 

int x, y, width, height; 

OBJECT ♦Un- 
reserved = form_center(tree, &x, & y, &width, &height); 

where tree is a pointer to the dialog object tree, and x, y, 
width, and height are the variables in which the routine returns 
the position and size of the centered dialog box. This routine 
computes the top left coordinates at which the dialog box will 
be centered on screen and writes those coordinates into the 
ob—X and ob—y fields of the root object. This step is necessary 
because the root objects created by the resource construction 
programs are all positioned at (0,0). If you don't center these 
objects before displaying them, dialog boxes will always be 
drawn in the top left comer of the screen, rather than in the 
middle. 

The next step is to use the form—dial( ) call to reserve the 
screen area in which the dialog is to be displayed. The syntax 
for this call is 

int status, action, smallx, smally, smallw, smallh; 
int largex, largey, largew, largeh; 

status = form— dial(action, smallx, smally, smallw, smallh, largex, 
largey, largew, largeh); 

where action is a flag which indicates the type of action you 
wish to take, and the two sets of rectangle information give 
the smallest and largest dimensions of the dialog box. The 
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four valid action-type flags (and the macro names for them 
defined in the GEMDEFS.H file) are as follows: 


Type 



Number 

Macro Name 

Action 

0 

FMD—START 

Reserves the screen area used by the dia- 
log box 

1 

FMD—GROW 

Draws expanding box from small to 
large rectangle 

2 

FMD—SHRINK 

Draws shrinking box from large to small 
rectangle 

3 

FMD— FINISH 

Frees the screen area used by the dialog 
box, and causes redraw messages to be 
sent 


The type of action that is appropriate at this stage of the 
dialog presentation is FMD—START, which reserves the screen 
area that will be used by the dialog box. If you've read the of- 
ficial GEM documentation, you may have noticed that the 
syntax for the C binding shown there includes only one set of 
rectangle parameters. The actual binding, however, uses the 
format shown above. Although only the two middle action 
types — FMD—GROW and FMD—SHRINK — use both sets of 
rectangles, you must supply dummy parameters as place hold- 
ers when you use the other two action types. For example, a 
typical FMD—START command would take the form 

form— dial(FMD_START, 0, 0, 0, 0, x, y, width, height); 

The next step is completely optional. If you wish, you 
may call form— dial using the FMD—GROW subcommand. This 
step animates a zoom box which moves and grows from the 
first rectangle to the second one. While this may add a bit of 
visual appeal to your program, it also causes a slight delay 
which may irritate the more advanced user. Generally, it's best 
not to include it unless it gives the user some meaningful 
information. For example, if the user double-clicks on an icon 
to open a dialog box, then it may be helpful to show the dia- 
log box "exploding" from that icon to show the relationship 
between the two. If the dialog box was started up from a 
menu item, however, it really doesn't add anything to show 
the box exploding from the menu since the menu item disap- 
pears before you can tell where the zoom box is coming from. 
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Finally, you draw the dialog box using the objc—draw() 
command and animate it using form—do(). The syntax for the 
form_do( ) call is 

int exitobj, editobj; 

OBJECT ‘tree; 

exitobj *=> form_do(tree, editobj); 

where tree is a pointer to the dialog's object tree and editobj 
is the object number of the editable text object at which the 
cursor will first be placed. If there are no editable text fields, 
you should pass a value of 0 for editobj. The exitobj variable 
contains the number of the object whose selection caused 
the end of the dialog animation. If that object had the 
TOUCHEXIT flag set and was selected with a double-click, the 
high bit of the exitobj field will be set. If you use TOUCHEXIT 
objects and don't care to check for double-clicks, you may 
want to mask that bit off before checking the object number. 

When form_do( ) terminates, the dialog is still displayed 
onscreen. If the dialog has truly concluded, it's up to your 
application to clean up the screen. If you had used to 
FMD—GROW subcommand of form_dial( ) at the beginning of 
the dialog, you'll want to use the FMD_SHRINK subcommand 
of form_dial( ) to reverse the zoom box. 

After that (optional) step, you'll want to use the 
FMD—FINISH subcommand of form_dial( ) to release the 
screen area that had been reserved for the dialog and to re- 
store the screen. Since a dialog box can be considerably larger 
in size than one quarter of the screen, it's impossible to store 
the screen background in the menu/alert buffer. Therefore, 
the AES cannot automatically restore the screen background at 
the end of a dialog. Instead, it considers the screen rectangle 
described by the form_dial(FMD_FINISH) call as damaged 
and sends redraw messages to all of the windows within this 
area. If your program handles those messages already, then 
the redraw will be more or less automatic. 

You should make certain that the screen rectangle that 
you describe in the form_dial(FMD_FINISH) call really covers 
all of your dialog box. The x, y, width, and height values re- 
turned by form_center( ) allow for the OUTLINED state, 
which is the default for the root object of dialog boxes created 
with the resource construction programs. But it doesn't take 
outside borders into consideration. If you have a thick exterior 
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border, you may need to extend the size of the rectangle you 
describe in form_dial(FMD_FINISH). Note, however, that 
form_dial(FMD_FINISH) always sends redraw messages for 
an area two pixels wider and higher than the one specified, 
which means that you don't have to allow for the drop 
shadow under SHADOWED objects. 

Although form_dial(FMD_FINISH) was designed for dia- 
log handling, you may use it any time you wish to force a re- 
draw. This method is much handier than using the message 
pipe to send a redraw message directly, since the AES figures 
out which windows should get the message and sends them 
automatically. In addition, this call forces the AES to redraw 
the Desktop window in those areas not covered by application 
windows. Since more work is involved, this method is a bit 
slower than sending the redraw messages directly. 

Once your program has exited the dialog, there are still 
some tasks left to perform. First, you should deselect the exit 
button. You can do this either by using the objc-jchange( ) rou- 
tine or by directly resetting the SELECTED bit of the objects 
ob— state field. If you fail to do this, the next time the dialog is 
displayed, it will come up with the object used to exit the dia- 
log highlighted in inverse video. 

You must also note new selection settings for all the sig- 
nificant objects in the dialog. That includes any text that may 
have been entered into editable text objects. You should prob- 
ably transfer all the new settings to a separate array which 
keeps track of current settings. That way, your program won't 
have to keep checking the object fields to find the settings. 
Also, this practice will allow you to undo changes the user 
makes if he or she exits the dialog with the Cancel button in- 
stead of OK. 

Program 6-1 demonstrates some of the common features 
of dialog-box handling. 

Program 6-1. dialogic 

/***************************tt****tt**t****tst*t****t*****x*t*tttr*/ 


ft */ 

ft DIALOG1.C — Demonstrates handling of simple dialog tf 

ft box, with buttons, boxes and editable text. tf 

ft tf 


fttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttf 

tidefine APR INFO “ " 

tide-fine APP NAME "Dialog Example 1 M 

tide-fine WDW CTRLS (NAME) 
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tidef ine MOUSE OFF graf _mouse <M_OFF, 0L> 

Ode-fine MOUSE ON graf .mouse (M_QN,0L> 
tidef ine FALSE 0 
tide-fine TRUE I 

tidefine MAX(X,Y> ( (X) > <Y) ? (X) j <Y) ) 

Ode-fine MIN(X,Y> ( <X) < <Y> ? (X) s CY ) ) 

tiinclude "aesshell.c" 

tiinclude "dialogl.h" /* include file from RCS */ 


OBJECT tmenutree; 
OBJECT tdialtreei 
TEDINFO tobspec) 
char tstrptr; 


/% pointer to menu object tree */ 

/* pointer to dialog object tree t/ 
ft pointer to TEDINFO for text object %/ 
ft pointer to text string for text object tf 


int agesC33» C0, 0, 0>; 
int computersC43° <0,0,0,01? 
char lastxtC133a ,,M $ 
int left, top? 


ft array for age tally */ 

/* array for computer tally tf 
ft buffer for last "other” text */ 


demoO 

< 


int done “ 0) 
int msgC83? 

if ('rare load ("DIALQSl .RSC") ) /* Load resource file */ 

< 

f orm_alert <3, "C03 [Fatal ErrortCan’t find DIALOG!. RSC f i le ! DCAbort 3") ? 
return<0)j /* Abort if it's not there tf 

> 


/* get address of menu tree and dialog tree tf 

rsrc_gaddr (R TREE, MENUTREE, fcmenutree) j 

rsrc.gaddr (R_TREE, DIALTREE, fcdialtree); 

ft get pointer to text objects's text string tf 

obspec = < TED INFO *>dial treeC0THERTXT3.ob_spec? 

strptr = obspec— >te_p text ? ft pointer to text string tf 

strptrC03 = 0; ft clear out string tf 


MOUSE_QFF? 

menu_bar (menutree, 1 ) ; 
MGUSE_QNj 


ft Hide the mouse pointer tf 
ft Show the menu bar tf 
ft Show the mouse pointer */ 


/* Main Program Loop tf 


while (! done) ft until user selects "Quit" item */ 

< 

evnt_mesage (msg) ) ft check menus */ 

done = handle_msg (msg) y ft & handle messages tf 

> ft end of main WHILE loop tf 


menu_bar (menutree, 0) ? ft Remove the menu bar tf 


> /* end of DEMO function tf 


ft Message Handler routine — only handles menu messages tf 
ft and redraws (yours should also handle window topping, etc.) tf 

handle_msg (msg) 
int msgC83? 

< 


int done=0; 
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switch (msgC03) /t check message type tf 

{ 

case WM_REDRAWi /* if redraw, call refresh routine t/ 

refresh(msgt33, (GRECT *)8<msgC43); 
break; 

case MN_SELECTED* /% if menu message type %/ 
switch (msgC43) /* check menu item */ 
t 

case SURVITEh: ft Do Survey dialog tf 

do.dial () ; 
break; 

case QUITITEM: ft Quit */ 

done = 1; 
break; 
defaults 
break; 

> ft end of switch on menu item tf 

menu_tnormal (menutree, msgC33, 1); /* set menu to normal */ 
break; 

defaults 

break; 

>/* end of switch on message type tf 

return (done) ) ft report done status */ 

} 

ft Dialog Handler routine — Displays survey form tf 

do_dial () 
t 

int x, y, width, height, exitbutn; 

form center (di altree, 8tx, &y, Scwidth, 8<height); 
form_dial (FMD_START, 0, 0, 0, 0, x, y, width, height); 
ob jc_draw(dialtree, ROOT, MAX_DEPTH, x, y, width, height); 
exitbutn = form^do (di altree, OTHERTXT) ; 
check_ob js(exitbutn) ; ft check object states, etc. tf 

for medial (R1D_FINISH, 0, 0, 0, 0, x, y, width, height); 

> 

ftttttttt Sub-function to check dialog objects 
check_ob js (exitbutn) 
int exitbutn; 


0 

n 

n 




int x ; 

di al treeCexi tbutn] . ob_state SELECTED; ft de-select exit button tf 



for (x-YUNGBUTN; x < (OLDBUTN+1 ) ; x++> ft check radio button* */ 

jT 

if (dial treetx J . ob_state & SELECTED) 

( 

if (exi tbutn==OKBUTN) agesCx-YUNBBLiTN3++; ft increment age */ 
dial treetx 3. ob_state SELECTED; /* reset buttons */ 

> 

> 

for (x=STBOX; x< (0THERB0X+1 ) ; x++) /* check select boxes */ 

( 

if (di al treetx 3. ob_state & SELECTED) 

< 

if (exi tbutn==*QKBUTN ) computer stx-STBOX 3 ++; ft increment computers 
dial treetx 3. ob.state SELECTED; ft reset buttons tf 

> 

> 


n 

n 

n 

n 
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if ( ( strl on (strptr) >0) ScSc (exitbutn =» OKBUTN) ) 

strcpy (lastxt , strptr); ft if string not empty, copy */ 
strptr C03=*0; /* clear object string */ 


fttttttt Sub function to handle window refresh tttttttttttttt/ 


refresh (wh , drect ) 
int wh; 

BRECT tdrect; 

BRECT wrect; 


ft routine to handle window_ref resh (WM_REDRAW) */ 
ft window handle from msgC33 */ 
ft pointer to damage recatangle tf 

ft the current window rectangle in rect list */ 


M0USE_OFF ; /* turn off mouse */ 

wind_update (BE6_UPDATE) ; ft lock screen */ 


wind_get ft get first rectangle tf 

<wh7 WF_FIRSTXYWH, Sewrect. g_x, Sewrect. g_y, Sewrect. g_w, Sewrect . g_h) ; 


while ( wrect. g_w Gt8< wrect. g_h > 

if (overlap (drect, Sewrect)) 
f 

set_cl i p (Sewrect ) ; 

display (wh) ; 

vs_cl ip (handle, FALSE, 


ft while not at last rectangle, tf 

ft check to see if this one's damaged, 

ft if it is, set clip rectangle $/ 
ft redraw, and turn clip off tf 
(int >) Sewrect ); 


wind_get (wh, WF_NEXTXYWH, Sewrect. g_x , Sewrect. g_y, Sewrect. g_w, 
Sewrect. g_h) ; 

> 


*/ 


wind_updato (END_UPDATE) ; ft unlock screen */ 

MOUSE ON; ft turn mouse pointer back on tf 

> 


U 

u 



u 
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/ tttttttt Subfunction to draw the window display ttttttttttf 

display (wh) ft draw the window display tf 

int wh; 

C 

char buf C803; 

int x, y, width, height; 

wind_get(wh, WF_WORKXYWH, Sework.g.x, Sework.gjy, 

Scwork.g.w, Stwork.g_h); ft find work area */ 
clear_rect (Sework) ; ft and clear it */ 

form_center (dial tree, Sex, Sey, Scwidth, Seheight); 
left =* x ♦ cellw; 
top = y + cellh; 


sprintf(buf, "Computers M ); 

v_g text (handle, left, top+scellh, buf); 

sprintf(buf, " " ) ; 

v_gtext (handle, left, top+=cellh, buf); 

sprintf(buf, "Atari ST's =* 7. dX " , computersC03 ) ; 

v_gtext (handle, left, top+=cellh, buf); 

sprintf (buf, "Atari XL/XE's = 7.d7. ", computersC 1 3 ) ; 

v_gt ext (handle, left, top+=cellh, buf); 

sprintf (buf, "Exidy Sorceror's = 7.d7. " , computersC23 ) ; 

v.gtext (handle, left, top+=cellh, buf); 

sprintf (buf, "Other = V.d'f. ", computersC 33) ; 

v_gtext (handle, left, top+»cel 1 h, buf); 

sprintf (buf , "Others include: 7.s7. ", lastxt); 

v_gtext (handle, left, top+scellh, buf); 
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sprintf (buf, "Ages '•>) 

v_gtext (handle, left, top+=*(cel lh* 2 ) , buf>) 

sprintf (buf, M \ " ) j 

v_gtext (handle, left, top+°cellh, buf)| 
sprintf (buf , "Under 16 « Xd7. **,agesC0D)> 
v_gtext (handle, left, top+=cellh, buf); 
sprintf (buf, "16-39 » %dy. '^agesCn); 

v_gtext (handle, left, top+=cellh, buf); 
sprintf (buf, "Over 39 ® Xd7. ",agest23>) 

v^gtext (handle, left, top+=>cellh, buf)) 


> 

/* >>>>>>>> Utility routines used by other functions <<<<<<<<<<<<<< %/ 


□ 

n 

n 


set_clip(r) /* set clip to specified rectangle */ 
GRECT ir | 

int pointsC43; 

grect_conv(r , points)) 

vs_cl ip (handle, TRUE, points)) 

> 


overlap (rl, r 2 ) /* compute overlap of two rectangles */ 

GRECT *rl, *r2) 

< 

int x, y) 

x = MAX <r2->g_x , rl->g_x)) 
y = MAX (r2->g_y, rl->g_y>) 

r2->g_w = MIN7r2->g_x + r2->g_w, rl->g_x + rl->g_w> -x ; 
r2->g_h = MIN(r2->g_y + r2->g_h, rl->g_y + rl->g_h> -y ) 
r 2 ->g_x = x; 
r 2 ->g_y = y; 

return ( (r 2 ->g w > 0 ) && (r 2 ->g_h > 0 ) >5 

> 


ft it**************** End of Dialogl.c ************** */ 


In order to run this program, it's first necessary to create 
the resource file DIALOG1.RSC. This file contains two object 
trees, a dialog tree called DIALTREE, and a menu tree called 
MENUTREE. The dialog tree sets up a form for a computer 
survey. On the top line is a G_STRING that reads COM- 
PUTER SURVEY. On the next line is a G_STRING that reads 
Age:. Next to the G_STRING is a borderless G—IBOX that 
covers the rest of the line. Within that box are three radio but- 
tons, named YUNGBUTN, MIDBUTN, and OLDBUTN. Each 
of these buttons have the SELECTABLE and RBUTTON flags 
set. The text of YUNGBUTN reads Under 16, the text of 
MIDBUTN reads 16-39, and the text of OLDBUTN reads Over 
39. On the next line of text down is a G_STRING that reads 


n 

n 

n 

n 
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Computers Owned:. Under that string appears four G_BOXes, 
one on top of the other. Their names are STBOX, XLBOX, 
EXIDYBOX and OTHERBOX. Next to the top three boxes are 
G_STRINGS that read Atari ST, Atari XL/XE, and Exidy Sor- 
cerer. The fourth box, OTHERBOX, has a G—FTEXT next to it 
called OTHERTXT. The template for this text is Other: fol- 
lowed by 12 underscore characters. The validation string is 12 
n characters, and the text is 12 spaces. 

The menu tree has the default DESK and FILE titles with 
one menu item added to the FILE menu. Along with the QUIT 
item (whose name is QUITITEM), there's an item that reads 
Survey . . . whose name is SURVITEM. Using any of the re- 
source construction programs, it should be fairly easy to create 
the resource described here. If you don't have a resource con- 
struction program, you'll need to create the resource file from 
data arrays as shown in Appendix C. 

There are several interesting points to note about this pro- 
gram. First, note how the text of the editable string was reset 
by assigning a pointer to this string (named strptr), and then 
setting the first character of the string to ASCII 0 with the 
statement strptr[0] = 0;. This insures that when the dialog 
comes up, the editable text string will be blank, and the cursor 
will be positioned at the first character of the string. Before 
you clear out the string, however, copy the last string entered 
into the lastxt array, using the C function strcpyO. 

Another important point to note is how the program takes 
advantage of the object tree structure in tallying the votes 
from the form. Since the objects YUNGBUTN, MIDBUTN, and 
OLDBUTN are contiguous in the object array, it's possible to 
check their SELECTED flags by using a loop that runs from 
object YUNGBUTN to object OLDBUTN. The same is true of 
the G_BOX objects STBOX, XLBOX, EXIDYBOX, and 
OTHERBOX. You should create these objects one after the 
other with the resource construction program, in order to in- 
sure that they have consecutive object numbers. 

Although dialog boxes are an easy way to receive input 
from the user, they do have some drawbacks. For one thing, 
there are some bugs in the current (preblitter) implementation. 
For example, if the user enters the underscore character in an 
editable text field, the machine crashes immediately. Although 
Atari has promised to fix this rather serious flaw in the next 
version of the operating system, programmers might be wary 
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of using this potentially disastrous routine in their programs. 

The most serious problem with form_do( ) is that the rou- 
tine takes complete control of the program until the user hits 
the exit button. That means that while form_do( ) is executing, 
the user is stuck with providing input to the form and can't do 
anything else. The menu system doesn't work while a dialog 
is on screen, and if the user clicks on an object outside of the 
dialog box, all that happens is that a bell sounds. The reason 
for this is that form_do( ) itself uses the evnt—multi( ) call and 
only checks for keyboard and mouse button events. The 
evnt_multi( ) call takes place in a loop that keeps repeating 
until an exit condition occurs. 

Many programmers consciously try to avoid program 
modes. Form_do is modal by its very nature, since it puts the 
user into a form input mode, where he can do nothing but en- 
ter information, and where normal program features like 
menus don't work. Programmers who wish to design 
"modeless" programs, which allow the user to click on ob- 
jects, enter text, and use menus all at the same time, must 
therefore write their own form_do( ) equivalent, integrating its 
evnt_multi call into the program's main evnt_multi loop. Tim 
Oren, a member of the original GEM design team, has posted 
an excellent example of a user-defined form_do( ) routine in 
the Utilities Data Library (DL 3) area of the Ataril6 Forum on 
the CompuServe Information Service. The source code can be 
found in the file named GMCL13.C. 

The File Selector 

The final type of interactive form which the AES provides is 
the File Selector. The Library routine fsel—input( ) displays a 
complete prefabricated dialog box. The purpose of this dialog 
is to provide a standard method for showing the user the con- 
tents of a disk and allowing the selection of one of the files on 
that disk. The dialog box displayed by fsel_input( ) is shown 
in Figure 6-1. 

The current search path (drive name and subdirectories, if 
any) is shown on the line beneath the title Directory. The di- 
rectories and files found there are displayed in the window 
which is located in the lower left comer of the dialog box. A 
solid block with a white diamond shape in it appears before 
the names of directories, to distinguish them from files. There 
is a scroll bar at the side of the window, which may be used 


170 



Interactive Object Handling 




to view additional names if there are more than can fit in the 
box. If the user wishes to view a different drive or directory, 
he or she may change the display by clicking on the Directory 
blank and typing in a new file specification such as A: \ or 
C:\PROGRAMS. After typing in the new path, the user clicks 
anywhere within the filename window, and the AES updates 
its contents according to the new specification. If the user 
wishes to see the contents of any subdirectory whose name is 
in the window, he or she only has to click on the directory 
name, and the Directory specification will automatically be 
changed to show the contents of that subdirectory. 

A file may be selected in several ways. The user may type 
in the name of the file in the space marked Selection and then 
click on the OK button or press Return. A second way to se- 
lect the file would be to click on the name of the file in the 
window, which will cause that filename to appear in the Se- 
lection blank, and then click on the OK button or press Re- 
turn. Another way would be to double-click on the name of 
the file, which will both select it and choose OK. 

To display the File Selector dialog, you use the 
fsel—input( ) call, whose syntax is as follows: 

int status, exitbutn; 
char path[64], file[13]; 

status = fsel— input(path, file, &exitbutn); 


U 
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where path is a pointer to a string which contains the initial 
pathname and file is a pointer to a string which contains the 
default filename. The path string contains the drive letter, the 
subdirectory path, and the filename using a wild card, such as 
C: \ WORDPROC \ L + ETTERS \ *.DOC. The filename can be 
used to specify a default file or may be left blank. These same 
two variables are also used by fseL_input( ) to return the path- 
names and filenames selected by the user. If the Cancel button 
was selected, however, the original values will be unchanged 
upon exit from this routine. The exitbutn variable is where the 
routine returns the number of the button used to exit the dia- 
log (0 = Cancel, 1 = OK). 

The screen display isn't automatically restored upon com- 
pletion of the fsel_input( ) call. That's because the dialog box 
is larger in size than one quarter of the screen, so the screen 
background can't be saved in the menu/alert buffer. There- 
fore, when the function ends, the AES determines that the dia- 
log rectangle is "dirty,” and sends a WM—REDRAW to every 
application whose windows lay within the rectangle. If your 
program is prepared to handle WM—REDRAW messages, the 
display will be cleaned up as part of its routine message- 
handling chores. Note, however, that fsel_input( ) changes the 
current VDI clipping rectangle and doesn't change it back 
upon exit from the routine. Therefore, if your program does 
any VDI rendering after a call to fsel_input( ), you'll probably 
have to set the clipping rectangle afterward, whether you nor- 
mally use clipping or not. 

Program 6-2 demonstrates use of the fsel_input( ) routine to 
get a filename from the user. For purposes of brevity, this program 
simply clears the screen when it gets the WM—REFRESH message. 
In your own program, you would want to include an entire 
message-handling system that would take care of menu mes- 
sages, window topping messages, refresh messages, and so on. 

Program 6-2. fselect.c 

/tt*t**tt*t*tSt**t**t*t*tt***»**St**tt*tt>ttS**<t»ttStS***>Mt*t**t/ 


/* */ 

ft FSELECT.C — Demonstrates the use of the File */ 

ft Selector routine to obtain the pathname of a file. tf 

/* */ 

/* */ 


fttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttf 

#define APP_INFO ** ** Click on the Close Box to exit the program. 
#def ine APPiNAME "File Selector Demo" 

#def ine WDW CTRLS (NAME 1 CLOSER i INFO) 
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^include “aesshell.c" 

char {116064]; f% buffer for name of file selected */ 

char path 0643; /* buffer for search path */ 

char f ilespecC803; /* buffer for full pathname of file */ 

demo ( > 

0 

int msg083; 
int button, z; 

pathC03=Dgetdrv ( ) +'A' ; /* Set the drive name */ 

path 0 13°' i * ; 

DgetpatMf ile,0) ; /* and current directory path %/ 

street (path, file) ; 


fileC03 ° '\0'; 
street (path, M \\*. *" ) ; 
fsel_input (path, file. 


ft no initial file name tf 
ft set initial path */ 
^button); /* get file name t/ 


evnt mesage (femag) ; ft get the window redraw message, */ 

/* and handle it (sort of) */ 

graf_mouse (M_OFF, 0L); /* turn the mouse pointer off */ 

clear_rect (fcwork) ; /* clear the area */ 

graf _mouBe(M_ON, 0L) ; /* and turn it back on */ 


strepy <f ilespec, path) ; ft copy path to filespec buffer «/ 
z « strlen (f i lespec) ; /* remove characters from end.*, tf 

whiletz (ft lespec Oz—1 3 *\\*) ) 

z — ; /* until you get to backslash */ 

f ilespectz 3°' \0' ; 

streat (filespec, file); ft and add filename to path */ 


/* print complete path/filename tf 

v_gtext (handle, 10tcel lw, 10*cellh, filespec); 


evnt_mesage (fcmsg) ; ft & wait for the window close message */ 


> 

End of Fselect.c ******** tttttttttttttttf 


U 

u 




Although fsel_input( ) takes care of all of the interaction 
with the user, some additional steps are required before and 
after making the call. For one thing, the user may have put 
your program on a second floppy or hard drive, so it might be 
frustrating to find it if you always used the A drive for the de- 
fault search path. The safest course of action is to set the de- 
fault search path to the current directory, the one from which 
the program was run. In order to find the current directory, it's 
necessary to use a couple of GEMDOS routines. The first rou- 
tine is referred to by the macro name Dgetdru which is defined 
in the OSBIND.H file. This call returns the current drive num- 
ber (0 = A, 1 = B, and so on). The second routine is called 
Dgetpath. Given a pointer to a 64-byte buffer and a drive 
number (0 = current drive, 1 = A), this routine places a 
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string which specifies the directory path in the buffer. In the 
example program above, these two routines are used to build 
the default pathname. 

Another bit of manipulation is needed after fsel_input( ) 
returns the pathname and filename chosen. Since the path 
specifier will usually contain a wildcard for the filename, you 
have to eliminate each character from the end of the path 
string until you come to the backslash character. You can then 
tack on the filename to the end of the pathname. 

Although the File Selector does provide a uniform method 
for obtaining a filename from the user, it has some limitations. 
Chief among these is the fact that the filename window will 
only hold 100 entries. This means that if there are more than 
100 files in a directory, the user won't be able to view the last 
ones. Also, the file selector doesn't give the user any feedback 
on which drives are currently available. For these reasons, 
some programmers prefer to use their own file-selection dia- 
logs. If you are planning to do so, however, it would probably 
be a good idea to keep the form and function of this dialog as 
close to the standard one as possible. 

The fsel_input( ) routine is one that can be profitably 
used from a BASIC program. Program 6-3 demonstrates how 
to use this call from BASIC. Note that in this version of the 
program, the default path was set to A: \ *.*, since we are un- 
able make the necessary GEMDOS calls to determine the cur- 
rent path from the first version of STBASIC. Figure 6-2 
illustrates the file selector dialog box. 


n 

□ 

n 


Program 6-3. fselectbas 

10 • tmtmmmmmmtmimmimm* 

20 '* FSELECT . BAS — Demonstrates use of the * 

30 '* File Selector Library in ST BASIC * 

40 ’tt*«ttSS*S***S»***********S***S*SS******t* 

50 apbtt 3 gb 

60 CONTROL = peek (apbtt) 

70 GLOBAL = peek (apb#+4) 

80 GINTIN = peek (apb#+8) 

90 GINTOUT = peek (apb#+12) 

100 ADDRIN# = peek (apb#+16) 

110 ADROUT# = peek (apb#+20> 

120 fullw 2 

130 PATH*«"As\*. *" w Set pathname, and expand string to 64 characters 
140 PATHNAME*=PATH*+string* (58,chr* (0) ) 

150 FILE*="**+string*(12,chr*(0> ) 'Set filename to 13 nuls 

160 poke ADDRIN#,varptr (PATHNAME*) 

170 poke ADDRIN#+4, varptr (FILE*) 

180 gemsys(90) 'Call fsel inputO 

190 exitbutn = peek (GINTOUT+2) 

200 X =« 1 'Truncate file name 

210 while < ASC (mid* (FILE*, X, 1 ) ) < >0) 


n 

n 

n 

□ 
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220 X=X+1 

230 wend 

240 FXLE««1 ef tS (FILES, X ) 

250 X* 3 len( PATHNAMES) 'Truncate path name 

260 wh i 1 e < mi dS < PATHNAMES , X , 1 ) < > " \ M > 

270 X ■ X— 1 
280 wend 

290 PATHNAMES ° lefts (PATHNAMES, X) 

300 clearw 2tgotoxy 10,10 

310 print PATHNAMES+F I LES 

320 gotoxy 10, 12s 7 “Press any key to end. . • " i X=inp (2) 
330 clearw 2* end 


Figure 6-2. The File Selector Dialog Box 
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MOSt Of the graphics routines that GEM uses are 
found in the VDI graphics library. However, a few higher- 
level graphics routines were needed in order to implement the 
complicated object-manipulation routines of the Forms Library 
and some of the features of the GEM Desktop applications. 

These higher-level routines are found in the AES Graph- 
ics Library. These functions may appear to be so specialized 
that their usefulness is not readily apparent. When examining 
them, therefore, you should focus on the ways these routines 
are used by the GEM Desktop program. Then you should con- 
sider similar ways you might use them in your programs. 


Box Manipulation 

Many of the AES graphics routines are used to manipulate the 
rectangular outline of a box drawn on the screen. If you stop 
to think, you'll realize how much is done on just the Desktop 
program with boxes. Rectangular shapes are used for win- 
dows, icons, buttons, and slider bars. These shapes are moved, 
dragged, and sized with the help of the AES graphics routines. 

The first of these routines is used to draw a rubber box. 
This is a box composed of dotted lines. The upper left comer 
of the box remains fixed, but the lower right comer changes 
position as the user drags the mouse. As long as the user 
holds the left mouse button, the box is redrawn whenever the 
mouse pointer changes positions. When the button is released, 
the box is erased. The operation of the rubber-box routine 
should be familiar to anyone who has used the size box on a 
window. The name of the routine used to draw the rubber box 
is graf—rubberbox( ). The syntax for this call is 

int status, x, y, minw, minh, endw, endh 

status = gra£_rubberbox(x, y, minw, minh, &endw, &endh); 

where x is the x coordinate for the left side of the box, and y is 
the y coordinate of the top of the box. The variables minw and 
minh contain the minimum box width and height, respectively. 
When the function ends, the current box width and height are 
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returned in endw and endh. The function's error status is re- 
turned in the status variable. A status of 0 signals that an error 
occurred during the call, while a positive integer means that 
function completed without error. 

Typically, a program will only call this routine when it 
has determined that the mouse button is down. This may be 
determined by an evnt—multi( ) or evnt—button( ) call, or by the 
activation of an object whose TOUCHEXIT flag is set. When 
the call is made, the dotted outline of a box is drawn from the 
coordinates leftx and topy to the current mouse position. The 
function continues to track the mouse pointer until the user re- 
leases the left mouse button. 

The graf—dragbox ( ) function allows the user to drag a box 
within a boundary rectangle, such as a window or dialog box. 
As with graf_rubberbox( ), this function should not be started 
until the program has determined that the user has pressed 
the left mouse button down. When the function is called, it 
draws the box outline and redraws the box whenever the 
mouse pointer moves within the boundary rectangle, until the 
left mouse button is released. When the function ends, it 
erases the box outline and returns the ending position of the 
box. The syntax for the graf_dragbox( ) call is 

int status, width, height, beginx, beginy; 

int boundx, boundy, boundw, boundh, endx, endy; 

status = graf_dragbox(width, height, beginx, beginy, boundx, 
boundy, boundw, boundh, &endx, &endy); 

where width and height specify the size of the box. The vari- 
ables beginx and beginy contain the starting position of the 
box, while the variables boundx, boundy, boundw, and boundh 
describe the position and size of the boundary rectangle. 

When the user releases the mouse button, the function returns 
the ending mouse position in the variables endx and endy. 

The next box function, grafslideboxf ), is also used to 
move a box within a container. This function, however, is ob- 
ject-oriented. The function moves a box object (called a slider) 
that is located within a parent box object (known as the bar). 
As with some of the other box functions, the program calls 
this routine only after it has determined that the user has 
pressed the left mouse button. Typically, the program would 
make this call when form—do( ) exits and indicates that the 
TOUCHEXIT box inside the bar was the exit object. The 
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graf_slidebox( ) moves the slider within the bar whenever the 
mouse pointer moves toward either end of the parent box. 
When the user releases the mouse button, the function returns 
a number indicating the position of the slider within the bar. 
The calling syntax for graf_slidebox( ) is 

int status, parent, object, orientation; 

OBJECT *tree; 

position = graf_slidebox(tree, parent, object, orientation); 

where tree is a pointer to the object tree array containing the 
two box objects, parent is the number of the parent box object, 
and object is the number of the box object which it contains. 
Orientation is a flag which indicates whether the parent bar is 
oriented horizontally or vertically. If this flag is set to 0, the 
bar is horizontal and the slider moves left and right. If the flag 
is set to 1, the bar is vertical and the slider moves up and 
down. The final position of the slider is returned in the posi- 
tion variable. This value is a number in the range 0-1000 
which denotes the position of the center of the slider relative 
to its parent object. If the orientation of the bar is vertical, a 
position of 0 indicates that the slider is at the top of the bar, 
while a position of 1000 indicates that it's at the bottom. If its 
orientation is horizontal, a position of 0 indicates that the 
slider is at the left of the bar, while a position of 1000 indi- 
cates that it's at the right. 

Although graf_slidebox( ) draws the dotted outline of a 
moving box while the user drags the mouse, it does not actu- 
ally move the slider object after the user lets go. Therefore, 
your program must move the slider, by calculating a new 
object.ob—y or object.ob—x position and by using objc_draw( ) 
to redraw both the parent slide-bar object and the slider that's 
contained in it. The calculation is very similar to that used for 
window sliders. For a vertical slider, the formula would look 
like this: 

tree[SLIDER].ob_y = (long)slider_pos *(long)(tree[SLIDEBAR] 
.ob_height — tree[SLIDER].ob_height) /1000; 

The casts to type long are used to avoid overflow in the 
multiplication and division. Program 7-1 demonstrates how to 
use the graf_slidebox( ) function in conjunction with a 
TOUCHEXIT slider object to implement a slide bar in a dialog 
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box. It also demonstrates how to implement user-defined ob- 
ject types. In this dialog box, there are three user-defined se- 
lection buttons that are drawn as circles when not selected and 
as filled circles when selected. 

Program 7-1. dialog2.c 

/tttttttt* ***************************** ********** ******************/ 


/* */ 

ft DIALQG2. C — Demonstrates more sophisticated dialog */ 
/% box, with a slider and user~def ined objects. */ 
/* */ 


/******************************************************************/ 


n 

n 

□ 


(♦define APP_INFO " ” 

♦♦define APP NAME "Dialog Example 2“ 

♦♦define WDW~CTRLS (NAME) 

♦♦define TRUE 1 

♦♦include "aesshel 1 .c" 

(♦include M dialog2.h M ft include file from RSC */ 

OBJECT tdialtree; f% pointer to dialog object tree */ 

TEDINFO tobspec; /* pointer to TEDINFO for text abject */ 

char tstrptr ; /* pointer to text string for text object */ 

APPLBLK ublockC3J; /* APPLBLK defined in OBDEFS.H */ 

demo ( > 
i 

int x, y, width, height, exitbutn, slider.pos; 
int drawcodeO; 

if ( ! rsrc_load ( "DI AL082. RSC” ) ) /* Load resource file */ 

{ 

f orm_alert (3, " C03 CFatal ErrorlCan't find DIAL0S2.RSC f i le » 3 C Abort 1" ) ; 
return(0); /* Abort if it's not there */ 

> 

/% get address of menu tree and dialog tree */ 
rsrc.gaddr (R_TREE, DIALTREE, Scdialtree); 

/ * get pointer to text objects's text string %f 
obspec = (TEDINFO *)dialtreeENUMBER3.ob_spec; 
strptr = obspec->te_ptext; /t pointer to text string */ 


for (x=OPTIQNl j x< (0PTI0N3+I ) 5 x++) 

< 

ublocktx-CPTIQNll . ub_code = drawcode; / * set drawcode %/ 

dial treeCxl.ob_spec « (char t)&ublockCx~QPTIONll; /% to userblock */ 
dialtreeCx 3. ob_type = 6_PRO0DEF \ / * change object type */ 

> 




/* Display dialog box %/ 

f or m_center (dial tree, Sex, Sty, Stwidth, Scheight); 
form.dial (FMD_START, 0, 0, 0, 0, x, y, width, height); 
ob jc_draw(dialtree, ROOT, MAX_DEPTH, x, y, width, height); 

ft Main dialog animation loop */ 


n 

n 

n 
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ft until exit button hit */ 

while ( (exitbutn = f orm_do(dialtree, 0) ) •= EXITBUTN) 

C 

exitbutn 0x7fff ; ft mask off top bit of exit object tf 
ft <set by clicks on TGUCHEXIT) tf 
if (exitbutn = SLIDER) ft if exit object was SLIDER tf 
f 

ft allow slider to be dragged tf 

slider _pos ° graf _sl idebox (dialtree, SLIDEBAR, SLIDER, 1); 
ft set new SLIDER y position (use longs to avoid overflow) tf 
dialtreeCSLIDER3.ob_y a ( long) si i der_pos * 

(long) (di al tree! SLIDEBAR 3* ob_height - dial treeCSLIDERJ.ob_height) /100 ft 
ft redraw slider in new position tf 

objc_draw (dial tree, SLIDEBAR, MAX_DEPTH, x, y, width, height); 
ft display new post ion by changing text of NUMBER object */ 

sprintf (strptr, "XAd” , slider _pos> ; ft redraw text tf 
ft and redrawing the object */ 

objc_draw (dial tree, NUMBER, MAX_DEPTH, x, y, width, height); 
y ft end of if TOUCHEXIT */ 

> ft end of main WHILE loop tf 

form_dial (FMD_FINISH, 0, 0, 0, 0, x, y, width, height); 



U 

u 


> ft end of DEMO function */ 

/************ Draw user-defined object *****************************/ 

drawcode(pb) /* Sample user object drawing tf 

PARMBLK *pb; 

int pointsC43; 
int x, y, xr, yr; 

grect_conv (&pb->pb_xc, points); 
vs_cl ip (handle, TRUE, points); 

vswr.mode (handle, 1 ) ; 
vsf _col or (handle, 1); 
vsf _interior (handl e, 0); 
if (SELECTED & pb->pb_currstate) 
vsf winter ior (handl e, 1); 

vsf _peri meter (handl e, 0); 
vsl_width (handl e, 3) ; 
xr- pb- >pb_w/2; 
yr= pb->pb_h/2; 
x = pb->pb_x + xr; 
y = pb->pb_y + yr; 

if (pb- >pb_curr state == pb~>pb_currstate) 

v_el 1 arc (handl e, x, y, yr-2, 0, 3599) ; 

v_el 1 ipse (handle, x, y, xr-8, yr-6> ; 

return (0) ; 

> 


ft End of Djalog2.c »*»**«***#***» */ 


/* set fill to hollow */ 

/t If selected t/ 

ft use solid fill pattern */ 



U 
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In order to run this program, you must first construct the 
resource file DIALOG2.RSC. If you have a resource construc- 
tion program, you may do so by following the instructions be- 
low. If not, you may use the RSCBUILD program in Appendix 
C to build the resource from data. 

At the top right side is a STRING object whose text reads 
Slider Position:. Directly below that is a text object with the 
name NUMBER, whose initial text reads 0. To the right of 
these objects is the slide bar. It's composed of two box objects. 
The first, SLIDEBAR, is a long tall G_BOX with an outside 
border with a thickness of 1 pixel, and it is HOLLOW filled, 
which means that it is transparent. Inside this object is its 
child, SLIDER, a G_BOX with an inside border with a thick- 
ness of 1. SLIDER is filled with solid black (color 1) and has 
its TOUCHEXIT flag set. Finally, at the left of the dialog box 
are three G_BOX items stacked one on top of the other. These 
are called OPTION1, OPTION2, and OPTION3. They are 
HOLLOW filled, with an outside border one pixel in thickness, 
and they have the SELECTABLE flag set. These objects are 
used as stand-ins for the user-defined objects that will be in- 
stalled later in the program, since the resource construction 
programs don't let you create them directly. Each of these box 
objects has a STRING object to the right of it, whose text 
reads OPTION* where * is the option number. Figure 7-1 
shows the layout of the dialog as created with the resource 
construction program (left) and as displayed by the program 
once the user-defined objects are installed (right). 


Figure 7-1. The Dialog Box from Program dialog2.c 
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As mentioned above, the resource construction programs 
won't let you build user-defined objects directly. Therefore, 
you have to use G—OBJECTS and change some fields in the 
object structure. 

First, you've got to change the object type to 
G—PROGDEF. Next, you must change the ob—spec field to a 
pointer to an APPLBLK structure. This structure should con- 
tain the address of your object drawing code in its ub—code 
field. Note also that the object drawing code, drawcodef ), only 
has to draw the outline of the ellipse once. It uses pb—currstate 
and pb—prevstate to find out whether the code is being called 
from objc—draw( ) or objc—change( ). If both fields are the same, 
objc_draw( ) was called, and the ellipse is drawn. If not, only 
the filled-ellipse routine is called. The filled-ellipse routine de- 
termines whether the circle is blacked in. 

Graf—ivatchbox( ) is the last of the box graphics routines 
that should be called when the mouse button is first pressed 
down. This routine simply watches the mouse pointer position 
while the button is held down and reports whether it ends up 
inside or outside of a particular object rectangle when the user 
lets the button up. The graf_watchbox( ) routine is called by 
form_do( ) to insure that the user, in order to select an object, 
has both pressed the mouse button while the pointer was over 
an object and then let the button up while the pointer was still 
over that object. The most likely use that an applications pro- 
grammer would make of this routine would be in writing his 
or her own form_do( ) routine. The syntax for this call is 

int in_or_out, object, instate, outstate; 

OBJECT *tree; 

in_or_out = graf_watchbox(tree, object, instate, outstate); 

where tree is a pointer to the object tree and object is the num- 
ber of the objects whose rectangle you wish to check. The in- 
state and outstate variables should hold the value of the 
object's ob_state flag when the pointer is inside the object rec- 
tangle and when it's outside the rectangle, respectively. For 
example, a SELECTABLE object will be SELECTED when the 
pointer is over it and not SELECTED when the pointer is 
away from it. This allows the routine to change the state of 
the object and redraw it as the pointer is dragged. When the 
user lets the left mouse button up, the routine returns a flag in 
the variable in— or— out that indicates whether the pointer 
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ended up inside or outside of the object rectangle. A value of 
0 indicates that it was outside the rectangle, while a value of 1 
indicates that it ended up inside. 

The last box graphics functions are used mainly for cos- 
metic purposes. The first is used to draw the outline of a box 
moving from one point onscreen to another. It does this by 
drawing a series of boxes from the source point to the destina- 
tion point, one by one, and then erasing those boxes one at a 
time, in reverse order. All of this happens so quickly that the 
user gets the impression that something is zooming across the 
screen. Unless used to indicate a transition from one window 
another, this effect is mere window dressing, and as such is al- 
most always superfluous. The function used to create the ef- 
fect is called graf_mbox( ): 

int status, width, height, beginx, beginy, endx, endy; 

status = graf_mbox(width, height, beginx, beginy, endx, endy); 

where width and height specify the size of the box, beginx and 
beginy its beginning position, and endx and endy its final 
position. 

Note that the Digital Research documentation refers to 
this function as graf—movebox( ). However, the C language 
bindings released by Atari Corporation with the Alcyon C com- 
piler and libraries derived from Atari's code (such as those 
supplied with the Megamax compiler) use the graf—mbox() ter- 
minology. Therefore, in order to link properly with current 
versions of the library, your program must also use the 
graf— mbox( ) form. If, in the future. Atari decides to change its 
libraries to conform to its documentation, you'll need to 
change over to graf_movebox( ) as well. 

The last two box graphics calls, graf—growbox() and 
grafshrinkbox( ) are also used mainly for cosmetic purposes. 
These two calls are very similar to the FMD—GROW and 
FMD—SHRINK subcommands of the form—dial() routine. 
They draw a set of expanding or shrinking boxes from one 
screen rectangle to another, like graf_mbox( ) using different 
size boxes. You can create exploding windows by calling 
graf_growbox( ) just before wind-jopen(), and graf_shrinkbox( ) 
just after wind—close( ). The syntax for these two calls are 
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int status, smallx, smally, smallw, smallh; 
int largex, largey, largew, largeh; 

status = graf_growbox(smallx, smally, smallw, smallh, largex, 
largey, largew, largeh); 

status = gra£_shrinkbox(largex, largey, largew, largeh, smallx, 
smally, smallw, smallh); 

where smallx, smally, smallw, and smallh specify the size and 
position of the smaller rectangle, and largex, largey, largew, 
and largeh give the size and position of the larger rectangle. 
The status variable contains a 0 if an error occurred during the 
call; otherwise it contains a nonzero integer. 

Mouse Form 

One of the most commonly used AES Graphics Library call is 
the one that changes the shape of the mouse pointer. In GEM, 
the shape of the mouse pointer can be used to indicate what 
kind of action will take place when the user moves the mouse. 
For example, a pointing hand is often used for selection or for 
sizing a rectangle, while a flat hand can indicate that dragging 
will take place. When a program starts up from the GEM 
Desktop, the mouse pointer takes the form of the "busy bee," 
which indicates that the program is busy working, and the 
user will have to wait until it's finished to begin input. 

Normally, the program will change this pointer to the 
general-purpose arrow shape as soon as the program is ready 
for input. To do this, it uses the call graf—mouse( ). This routine 
allows the program to set the mouse pointer shape to one of 
eight predefined forms or to a user-defined 16 X 16-pixel bit- 
mapped image. It also can be used to temporarily eliminate 
the mouse pointer display and to restore the pointer again. It 
is necessary to hide the mouse pointer whenever your pro- 
gram does any drawing that might overwrite it, since the old 
background behind the pointer will be restored as soon as the 
pointer is moved. The syntax of the graf_mouse( ) call is 

int status, form— no, formptr[37]; 
status = graf_mouse(form_no, formptr); 

where form-.no indicates which form the user wishes to install. 
The valid form numbers and the macro names for them that 
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are found in the GEMDEFS.H file are shown below, along 
with a short explanation of the typical usage of these forms: 


Form 

Number 

Shape 

Macro Name 

Usage 

0 

Arrow 

ARROW 

General purposes 

1 

Vertical bar (I-beam) 

TEXT— CRSR 

Text cursor placement 

2 

Busy bee 

HOURGLASS 

Busy signal 

3 

Pointing hand 

POINT-HAND 

Sizing 

4 

Flat hand 

FLAT— HAND 

Dragging 

5 

Thin crosshairs 

THIN-CROSS 

Drawing 

6 

Thick crosshairs 

THICK— CROSS 

Application-specific 

7 

Outline crosshairs 

OUTLN— CROSS 

Application-specific 

255 

User defined 

USER— DEF 

Application-specific 

256 

Mouse pointer off 

M_OFF 

Hide mouse before 

257 

Mouse pointer on 

M_ON 

drawing 

Restore 


When form number 255 — the user-defined pointer im- 
age — is selected, the formptr value should contain the address 
of a 37-word data array that provides information about the 
pointer. This information includes the foreground and back- 
ground colors for the pointer, the shape of the pointer, and a 
mask which allows you to specify whether the zero bits in the 
16 X 16 block are transparent (don't replace existing back- 
ground with a new color) or opaque (replace existing back- 
ground with the pointer background color). It also includes the 
coordinates of the pointer's hot spot or action point. The hot 
spot is the single pixel which is considered to be the pointer's 
location on the screen, even though the pointer may be much 
larger than a single point. On the arrow-shaped pointer, for 
example, the hot spot is located at the very tip of the arrow. If 
you click on an icon with the tail of the arrow, rather than 
with the point, nothing will happen. On the bee-shaped 
pointer, the hot spot is at the center of the image. The layout 
of the mouse form definition data structure is as follows: 

Element Meaning 

0 x position of "hot spot" 

1 y position of "hot spot" 

2 Number of bit planes (must be set to 1) 

3 Background color (normally 0) 

4 Foreground color (normally 1) 

5-20 16 words of color-mask data 

21-36 16 words of image data 
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The x and y coordinates of the hot spot are measured as 
an offset from the top left comer of the 16 x 16-pixel block. 
The image data block is laid out so that each line of the image 
is represented by one 16-bit word, with the most significant 
bit of the word representing the leftmost dot and the least sig- 
nificant bit representing the rightmost dot. Each bit position 
that contains a 1 is colored with the foreground pen, and each 
bit position that contains a 0 is colored either with the back- 
ground pen, or whatever color is displayed by the existing 
background, depending on the color mask. 

The color mask is used to define the shape of the pointer, 
without regard to color information. Those bit positions con- 
taining a 1 are considered to be inside the pointer. They will 
be colored with the foreground pen if the corresponding bit 
positions in the image data also contain a 1. They will be col- 
ored with the background pen if the corresponding bit posi- 
tions in the image data contain a 0. Those bit positions which 
contain a 0 are considered to be outside the pointer image 
and, therefore, are transparent. Whatever background image 
exists on the screen will continue to be displayed at these 
points. 

It is important to use both foreground and background 
pens in your pointer, in order to insure that it remains visible 
against any kind of background. Even though the normal sys- 
tem pointers such as the arrow appear to be black only, there 
is actually a thin white line surrounding them. This makes it 
possible for the user to see the arrow, even when it's in front 
of a solid black background. 

Program 7-2, written in C, shows how to use evnt__mouse( ) 
or the mouse rectangle function of evnt_multi( ) to track the 
mouse pointer and change its shape as it moves into different 
regions of the screen. It draws a box in the center of the screen 
and changes the pointer shape as it moves into the areas above, 
below, to the right, and to the left of the box. When the 
pointer moves into the box itself, it changes to the user- 
defined shape whose data is stored in the array called pointer. 
This pointer is supposed to look like the ST mouse itself, 
though the resemblance is better in high- or low-resolution 
mode than in medium resolution. 
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Program 7-2. mousform.c 


/****************************************************************««/ 
ft */ 

ft MOUSFDRM.C — shows how to change the mouse pointer */ 

/* shape as the pointer moves around the screen. */ 

/* */ 

/* */ 


/******************************************************************/ 

tide-fine APP_INF0 " ** Click on the Close Box to exit the program. **" 
tide-fine APP_NAME "Mouse Form Demonstration Program" 
tide-fine WDW_CTRLS (NAME I CLOSER I INFO) 

tiinclude "aesshell.c" 

ft Data -for our own custom "mouse" pointer tf 

int pointerC373 = 

C 

0,0,1, ft x and y of hot spot tf 

0,1, ft background and foreground pens */ 

ft 16 words of color mask data tf 

0xF000, 0XF800, 0X7DC0, 0x3FE0, 0x 1FF0, 0xlFF8, 0xlFF8, 0x3FFC, 
0X7FFE, 0x3FFF, 0X1FFF, 0x0FFF,0x07FF, 0X01FE, 0X00FC, 0x0078, 

ft 16 words of image data tf 

0XC000, 0x7000, 0x1080, 0x 1D40, 0X0E20, 0x0410, 0X0A28, 0x1148, 
0x2084, 0x1102, 0X0A01 , 0X0401,0X0302, 0x0084, 0x0048, 0x0030 

>1 

int points! 103; ft array of points for box tf 
demo ( ) 

int event, done = 0; 
int dummy, msg!83) 
int mx, myj 

GRECT rj ft mouse rectangle to watch */ 

ft set points for center rectangle */ 

pointsC03 = points£63 = pointsC83 «=■ work.g_x + (work . g_w/3) ; 

points! 1 3 = points£33 = points£93 « work.g_y + (work.g_h/3> ; 

points£23 = points!43 = work.g_x + (work.g_w * 2 /3) ) 

points!53 = points!73 = work.g_y + (work.g_h *2/3) ) 

/* draw box, find mouse position, and set pointer shape accordingly */ 
graf _mouse (M_OFF, 0L) | 
v_pl ine (handle, 5, points)) 
graf_mkstate((cmx, &my, ((dummy, ((dummy); 
setjstr<mx, my, !*r)| 
graf_mouse(M_CN, 0L) ) 

/* Main Program Loop */ 

while (! done) ft until user clicks on close box */ 

C ft check messages and mouse rectangle */ 

event = evnt_multi <MU_MESAG IMUJ11 , 

0. 0.0, ft evnt.button tf 

1, r.g_x, r . g_y , r . g_w, r.g_h, ft evnt_mousel tf 

0,0, 0,0,0, ft evnt_mouse2 tf 

&msg, ft evnt_mesg */ 

0,0, /* evnt_timer tf 

&mx,&my, ft mouse x,y tf 

((dummy, ft mouse button tf 

((dummy, ft shift keys tf 
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Scdummy, ft evnt_keyboard */ 

Stdummy); ft number of clicks tf 

if (event & MU_MESAG) /* if we get a window close message, */ 
if (msgC0J «= «M_CLOSED> /* we’re done */ 
done « 1; 

if (event MU_M1) /* if mouse leaves rectangle, change pointer tf 
set_ptr(mx, my, &r); ft and reset rectangle to watch tf 

> ft end of main WHILE loop tf 
> ft end of demoO function */ 

/ tttttttttttttt Pointer change routine ttttttttttttttttttttt ttttf 

se t_ptr (x, y, r) 

int x, y| ft mouse x, y */ 

GRECT $rj ft new rectangle to watch tf 
t 

int form; 

if (y < work.g y) ft if above window work area tf 
C 

form = 0; ft set to arrow shape */ 

r->g_x *» 0; 
r — >g_y ** 0; 

r->g_w = work . g_w; 
r — >g_h = work.g_y—l; 

> 

else if <y < pointed]) ft if above center box */ 
i 

form =3} ft set to pointing hand */ 

r — >g_x » work.g_xj 
r — >g_y a work.g_y; 
r — >g_w = work.g_w; 
r — >g_h = work.g_h/3; 

> 

else if(y > pointstSD) ft if below center box tf 
i 

form a 4j ft set to open hand tf 

r — >g_x = work.g_x; 

r — >g_y = work.g_y + (work.g_h * 2 / 3> ; 
v — >g_w » work.g_wj 
i — >g_h = work.g_h/3; 

> 

else if(x < poi ntsC03 ) ft if left of center box tf 
C 

form = 9| ft set to thin cross hairs tf 

r->g_x = work . g_x ; 

r->g_y « work.g_y + (work.g_h / 3>$ 
r->g_w o work.g_w / 3} 
r->g h « work.g h/3; 

> 

else if(x > pointsC2J) ft if right of center box tf 
€ 

form ■ 6| ft set to thick cross hairs */ 

r->g_x » work.g_x + (work.g.w *2 / 3) | 
r — >9_y “ work.g_y + (work.g_h / 3) j 
» — >g_W = wor k . g_w /3j 
r — >g„h = work.g h/3| 

> 

else /t if IN center box tf 

< 

form = 2SSj ft set pointer to user — defined shape */ 
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r->g_x = pointsC03; /* (looks like the mouse, sort of) */ 

r — >g_y 15 pointed 3; 

r->g_w a poi nt sC 4 3 - points£03 + 1) 

r->g_h « pointsC53 - points! 13 + 1) 

> 

graf .mouse (-form, pointer); 


> /* end o-f set_ptr(> */ 

/imitsttmmmt* End of Mousform.c ttttttttttttt*/ 


n 

n 

n 


Program 7-3 is a machine language version of the same 
program. 

Program 7-3. mousform.s 

************************************************************ 

* * 

* MOUSFORM.S — Shows how to change pointer shape * 

* * 
************************************************************ 


*** External references 
** Export: 

.xdef demo * external demo subroutine, 

.xdef wdwctrl 

.xdef wdwtitl 

.xdef wdwinfo 

** Import: 

.xref vdi 

.xref aes 

•xref vwkhnd * virtual workstation handle, 

.xref contr 1 0 * all of the VDI data arrays 

.xref contr 11 

.xref contr 12 

.xref contr 13 

•xref contrl4 

.xref contrlS 

•xref contr 16 

•xref intin 

•xref ptsin 

•xref ctrl0 * all of the AES data arrays 

.xref ctrl 1 

.xref ctrl2 

.xref ctrl 3 

.xref ctrl4 

•xref aintin 

•xref aintout 

•xref addrin 

.xref deskx 

•xref desky 

•xref deskw 

.xref deskh 

.xref workx 

•xref worky 

.xref workw 

.xref workh 


n 

n 

n 

n 

n 


192 



u 

u 


The Graphics Library 






U 

U 

u 

u 


.text 


demos 

move 40, d4 * close window flag in d4 

jsr mousoff 

move 46,contrl0 (opcode for polyline 

move 45,contrll * number of points in ptsin 

move 40,contrl3 ( no integer parameters in intin 

move vwkhnd,contrl6 (virtual workstation handle 


sub. 1 

d0, d0 


move 

workw, d0 

* find left side of box 

divu 

43, d0 


move 

d0, thirdw 


add 

workx , d0 


move 

d0, left 


move 

d0, ptsin 


move 

. d0,ptsin+12 


move 

d0, ptsin+16 


add 

thirdw, d0 

* find right side of box 

move 

d0, right 


move 

d0,ptsin+4 


move 

d0, ptsin+S 


sub. 1 

d0, d0 


move 

workh,d0 

* find top side of box 

divu 

43, d0 


move 

d0, thirdh 


add 

worky, d0 


move 

d0, top 


move 

d0,ptsin+2 


move 

d0,ptsin+6 


move 

d0, ptsin+18 


add 

thirdh, d0 

* find bottom side of box 

move 

d0, bottom 


move 

d0,ptsin+10 


move 

d0,ptsin+14 


jsr 

vdi 

* draw box 

((( find 

current mouse position 

move 

479,ctrl0 

( opcode = graf_mkstate 

move 

40, Ctrl 1 

* no intins 

move 

45,ctr 1 2 

( 3 intout 

move 

40, ctr!3 

( 0 addrin 

isr 

aes 


*** set 

pointer shape accordingly 

jsr 

setptr 


isr 

mouson 


(** main 

program loop 


main: 



move 

423,ctrl0 

t opcode = ©vnt_multi 

move 

416, Ctrl 1 


move 

47, Ctrl 2 

* 1 intout 

move 

41 , Ctrl 3 

* 1 addrin 

move 

40, ctr 14 


move 

420, aintin 

* waiting for message or 

move. 

1 4msg,addrin 

( message buffer address 

move 

41 , aint m+8 

* mouse rectangle 1 flag 
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jsr 

aes 


move 

440, Ctrl 3 


move 

aintout, d5 


cmpi 

444, d5 

* did we get a mouse rectangle event? 

bne 

message 


jsr 

setptr 

t if so, change pointer form 

bra 

skip 


message: 



move 

msg, d6 

* if not, check message type 

cmpi 

4422, d6 

* WM_CLOSED? 

bne 

skip 


move 

441, d4 

* yes, set close flag 

skip: 



cmpi 

440, d4 

t check if close flag set 

beq 

main 

* if not, keep going 

rts 




>t >>>>>>>>>> End of Main Program Code <<<<<<<<<<<<<<<< ** 

ttt turn mouse off or on or change pointer shape 
setf or ms 


move 

d7,aintin * 

form number 

bra 

mouse 1 


mousof f : 

move 

44256, aintin * 

hide the mouse 

bra 

mouse 1 


mouson; 

move 

44257, aintin * 

show the mouse 

mouse 1 : 

move 

#78, Ctrl 0 * 

command «* graf_mouse 

move 

#1 , Ctrl 1 * 

1 input integers 

move 

#1 , Ctrl 2 * 

1 output integer 

move 

#1 , ctrl3 * 

1 input address 

move* 1 

#poi nter , addr i n 

jmp 

aes 



ttt set pointer form and new rectangle to watch 

# setptri 

move 
move 
move 
cmp 
bhi 
move 
move 
move 
move 
subq 
move 


setptl s 


move 

thirdh, aintin+16 

t 

al 1 of 

the rest 

are 1/3 window high 

move 

workx , aintin-*- 10 

t 

next 3 

start at 

left 

cmp 

top,dl 

t 

if above center 

box 

bhi 

setpt2: 





move 

#3,d7 

t 

set to 

pointing 

hand 

move 

worky, aintin+12 





bra 

setpt6: 






aintout+2,d0 t mouse x position 

aintout+4, dl * mouse y position 

workw, aintin+14 * next 3 are full window wide 

worky, dl t above window work area? 

setptl 

410, d7 * if so, change form to arrow 

440, ainti n+10 

440, aintin+12 
worky, d2 

441, U2 

d2, ainti n+16 
eetpt6: 





u 
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setpt2t 


cmp 

bottom, dl 

% 

bcs 

setpt3s 


move 

#4,d7 

t 

move 

bottom, ai nt i n+1 2 


bra 

setpt6: 


setpt3s 

move 

thi rdw, ai nt i n+14 

t 

move 

top, aintin+12 

t 

cmp 

left,d0 

t 

bhi 

setpt4: 


move 

#5,d7 

% 

bra 

setpt6: 


setpt4: 

cmp 

right, d0 

t 

bcs 

setpt5: 


move 

#6, d7 

t 

move 

right, aintin+10 


bra 

setpt6: 


setpt5s 

move 

#2S5,d7 

% 

move 

left, aintin+10 

% 

setpt6: 

imp 

set form 



if below center box 
set to open hand 

next 3 all are 1/3 window wide 

and y is at top 

if at left of center box 

set to thin cross hairs 

if at right of center box 
set to thick cross hairs 

if in center box, set to custom 
pointer shape 


u 

u 




*** Storage space and data constants 


• data 
.even 


meg: 

lefts 

rights 

tops 

bottom: 

thirdws 

thirdhs 


• ds.w 

• ds.w 

• ds. w 

• ds.w 

• ds.w 

• ds.w 

• ds.w 


* buffer for message event 


wdwtitl : 

• dc.b 

' Mouse 

Pointer Demonstration', 

,0 

* text of window 

wdwinf os 

. dc.b 

'Click 

close 

box to end ',0 

* 

text of window 

info 

wdwctrl t 

. dc. w 

19 


* window 

control flag 


pointers 

. dc. w 

0,0,1 


* x and y 

of 

hot spot 



• dc. w 

0,1 


* background 

and foreground 

pens 

t 16 words 

of color mask data 

* 





• dc. w 

♦F000, 

*F800, 

S7DC0, *3FE0 





• dc. w 

*1FF0, 

*1FF8, 

S1FF8, *3FFC 





. dc. w 

*7FFE, 

*3FFF, 

S1FFF, S0FFF 





. dc. w 

*07FF, 

*01FE, 

*00FC, *0078 




* 16 words 

of image data * 






. dc. w 

*C000, 

*7000, 

*1080, * 1 D40 





. dc. w 

S0E20, 

*0410, 

S0A28, *1148 





. dc . w 

*2084, 

*1102, 

*0 A0 1 , *0401 





. dc . w 

*0302. 

*0084 , 

*0048, *0030 





. end 
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Mouse and Keyboard Input 

The final graphics routine is used for graphics input — which 
roughly translates to receiving information from the mouse 
pointer and shift keys. The graf—mkstate( ) call provides some 
of the same information as the evnt_button( ) and evnt_multi 
calls. The difference is that graf_mkstate( ) doesn't wait until 
an event occurs. Rather, it returns immediately, reporting the 
current status of the mouse buttons and shift keys. This makes 
it suitable for use in a polling routine that checks one or both 
of the mouse buttons. The format used for calling for this rou- 
tine is 

int reserved, mousex, mousey, mousbutn, shiftkey; 
reserved = graf_mkstate(&mousex, &mousey, &mousbutn, 
&shiftkey); 

where mousex and mousey contain the horizontal and vertical 
coordinates of the mouse pointer, and mousbutn and shiftkey 
contain information concerning the mouse button and shift 
key status. The mouse button state at the time of the call is re- 
turned in the mousbutn variable. The value returned is a 1 if 
the left button is down, 2 if the right button is down, or 3 if 
both are down. The shiftkey variable contains a code that tells 
whether the right Shift key, the left Shift key, the Control key, 
or the Alt key was pressed at the same time as the mouse but- 
ton. Each of the four low bits represents a different key: 

Bit 

Bit Value Key 

0 1 Right Shift 

1 2 Left Shift 

2 4 Control 

3 8 Alt 

Thus if shiftkey contains a 4, the Control key was held 
down when the mouse button was pressed, and if it has a 
value of 12, both Alt and Control were held down. The re- 
served variable is reserved for future use. Currently, a 1 is al- 
ways returned in the reserved variable. 

Since the current version of ST BASIC doesn't include any 
commands for checking the mouse, the graf_mkstate( ) func- 
tion can be very useful to BASIC programmers. The following 


196 



The Graphics Library 




U 

u 

u 


short sample program shows how to use graf_mkstate from 
BASIC. It merely waits for the user to press a mouse button 
and then tells him or her which button was pressed, the loca- 
tion of the mouse, and shift-key status code. 

Program 7-4. mous.bas 

10 apb# = gb 

20 control =* peek (apb#) 

30 global “ peek(apb#+4) 

40 gintin « peek <apbtt+8) 

50 gintout = peek < apb#+ 1 2) 

60 addrin “ peek <apb#+16) 

70 addrout = peek (apb #+20) 

80 fullw 2i clearM 2: gotoxy 1,1 

90 print "Press a mouse button to continue"*?:? 

100 mousbutn a 0 

110 whi le(mousbutn=0) 

120 gemsys<79): REM call graf_mkstate until a button is pushed 
130 mousex = peek <gintout+2) 

140 mousey « peek (gi nt out +4) 

150 mousbutn = peek (gin tout +6 ) 

160 shiftkey ® peek (gintout+8) 

170 wend 

180 if mousbutn > 0 then b*»"the left" 

190 if mousbutn > 1 then b*="the right" 

200 if mousbutn > 2 then b*="both" 

210 print " You pressed ";b*|" mouse button(s)" 

220 print 11 while the mouse was located at mousex mousey 

230 print " Shift key status was" j shift key 


U 

u 

u 

u 

u 
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The programs discussed so far have been 

applications run by double-clicking their icons from the Desk- 
top. As stated early on, however, GEM supports another type 
of program as well. This type of program is called a desk acces- 
sory, because of its ability to run concurrently with the Desk- 
top or any other application program that has installed a 
menu bar. 

Desk Accessories 

Desk accessory programs are loaded at boot time. These in- 
clude all programs located in the root directory of the boot 
disk (either the floppy disk in the A drive or the C partition 
on the hard disk) which have the extender .ACC attached to 
their names. There may be a maximum of six of these pro- 
grams. Desk accessory programs are started by selecting the 
menu item associated with them from the DESK menu at the 
far left side of the menu bar. 

There are several small but important differences between 
writing a desk accessory program and writing a normal 
application. 

The first difference is in the initial code used to start up 
the program. When an application program starts, it is given 
control over the entire Transient Program Area (TPA), which 
consists of all of the free system memory. Normally, the appli- 
cation will give back any memory that isn't used for program 
code, data, or the stack. It does this either in a machine lan- 
guage SETBLOCK call or in a C module that is linked in 
before the program object module. For example, Alcyon C us- 
ers must always link the file GEMSTART.O or APPSTART.O 
before the program module. In Megamax C, the file INIT.O, 
which is part of the SYSLIB library, is linked in automatically. 

A desk accessory, however, isn't assigned any free mem- 
ory when it's loaded at boot time. Therefore, a different 
startup module must be used, so the desk accessory doesn't 
try to give back extra memory that isn't there. In the case of 
Alcyon C, you must link the module ACCSTART.O first, in 
place of GEMSTART.O or APPSTART.O. With Megamax C, 
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you have to link in the ACC.L library file after your program 
object file. This will automatically override the INIT.O module 
in the SYSLIB library. 

Since desk accessory programs are started from the DESK 
menu, they need a way to enter text strings into the menu. 
They do this using the menu—register() call. The syntax for this 
call is 

extern int gl_apid; 

int menuid; 

static char ’menutext; 

menuid = menu— register(gl_apid, menutext) 

where gl—apid is the application ID number which is assigned 
to the desk accessory and stored in its global array when it 
calls appl—init( ). Menutext is a pointer to the null-terminated 
character array that holds the text of the menu item. 

Normally, the initial lines of a desk accessory program 
would look like this: 

appL_init( ); 

menuid — ' menu— register(gl_apid, “Accessory Name"); 

The function returns a menu ID number in the menuid 
variable. The ID number is used to identify which menu item 
was used to start the accessory program. This is necessary be- 
cause a single accessory can register more than one menu 
item. For example, a single accessory program displays both 
the control panel and printer setup menu items. Note, how- 
ever, that there are only six menu slots available on the DESK 
menu. When these are used up, no additional desk accessories 
may be loaded. This means that each additional menu item 
used by an accessory reduces the total number of desk acces- 
sories that may be loaded. For this reason, your accessory 
should stick to one menu item and use its own system for pre- 
senting multiple functions, such as a dialog box. 

The AES uses the message system to inform a desk acces- 
sory when one of its menu items is selected. Since the desk 
accessory has no control over the menu bar, it can't use the 
MN_ SELECTED message the way regular applications can. 
Instead, the AES sends it an AG_ OPEN message. The format 
for this message is as follows: 



n 

n 





n 

n 
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Word 

Number Contents 

0 40 (AC_OPEN), the message ID number 

4 The menu item number (menuid) of the desk accessory 
the user selected 

The number in word 4 of the message buffer contains 
the menuid that was returned when the accessory called 
menu_register( ). You should be aware that this practice dif- 
fers from Digital Research's GEM documentation, which states 
that the menu ID is returned in word 3 of the message buffer. 
(You should also be aware that the GEM documentation 
shows the message numbers for AC_ OPEN and AC-CLOSE 
to be 30 and 31. Actually, they are 40 and 41, respectively.) 

When the user closes the main application program and 
returns to the Desktop, the desk accessory's windows are 
automatically closed and deleted. The AES informs the acces- 
sory that this has happened with the AC-CLOSE message, 
which has the following format: 

Word 

Number Contents 

0 41 (AC— CLOSE), the message ID number 

3 The menu item number of the desk accessory whose win- 
dow handles have been lost due to closure of the main 
application 

The main difference between a desk accessory program 
and an application program, therefore, is that the desk acces- 
sory usually doesn't open a window until its menu item is se- 
lected and that the desk accessory program never ends and 
returns to the Desktop. Though the desk accessory may close 
its windows (or have them closed for it), it always remains 
loaded in memory, waiting for the user to select its menu 
item. Therefore, desk accessory programs are structured a bit 
differently from normal applications. After a short initializa- 
tion process, during which they call menu— register( ), they en- 
ter an endless loop centered around an evnt— multi( ) call, 
which waits, among other things, for the user to select the 
accessory's menu item. The following C sample program dem- 
onstrates a simple desk accessory. It is an adaptation of the 
message.c program found in Chapter 3. 
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Program 8-1. deskacc.c 

/tmmmitmmmmmmmmitmmmmuumtmttt**/ 


/* */ 

ft DESKACC.C — A modification of MESSAGE. C, to make it */ 

ft work as a desk accessory. tf 

ft tf 


fttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttf 

•include <osbind.h> /* Macro definitions for BIOS calls tf 
•include <gemdefs.h> /* Flag definitions for Library routines */ 
•include <obdefs.h> ft Object definitions tf 

•define FALSE 0 
♦♦define TRUE 1 
•define NONE -1 
•define APP_INFO "" 

•define APP NAME "Accessory Window" 

•define WDwIcTRLS (NAME t CLOSER t S I ZER ! MOVER I FULLER ) 

•define MAX(X,Y> ( <X) > <Y> ? (X) * (Y) ) 

•define MIN(X, Y) ( (X) < (Y> ? (X) 3 (Y) ) 


•define DESK 0 
•define NO_ERR 0 
•define APP ERR 1 
•define VWK ERR 2 
•define WDW_ERR 3 


ft The flag for the Desktop Window tf 
ft Error no. for "no error" */ 

/* Error no. for failure of appl_init<) tf 
ft Error no. for failure of v_opnvwk<> tf 
ft Error no. for failure of wi_create<) */ 





/* Global variables — For VDI bindings and program routines tf 

extern int gl_apidj ft The application ID part of the global array tf 
int ap_id; 


int contrlC121, ft VDI data arrays tf 

intinC12B3, 
ptsinC 1283, 
intoutC12B3, 
ptsoutt 1283 ; 


int phys_handle, 
handle, 
wi_handle, 
menuid, 
msgCB3; 


ft workstation handle for 
ft workstation handle for 
ft window handle tf 
ft menu id number tf 
ft message buffer tf 


physical screen device */ 
virtual screen device tf 


int work_inC123, ft input and output arrays for v_opnvwk() */ 
work_outC573 | 

6RECT desk, work; ft Desktop and application window dimensions tf 


int cellw, cellh, chspcw, chspch; ft size of default character font tf 


ft Program starts here tf 

mainO 

C 

int error; /* Error flag */ 


error 


i ni t_acc ( > ; 


ft Initialize application, open workstation, tf 
ft and open application window tf 


if ('error) ft If 

C 

while (1) 

< 

evnt_mesage (femsg) ; 
handle_msg ( ) ; 


no initialization failures, 

/* forever... tf 

ft get messages. • • */ 
/* and handle them, tf 


tf 


n 

n 





204 



u 

u 

u 




u 

u 

u 

LI 



Desk Accessories 


> /* end of while */ 

> /* end of if «/ 

> /% end of main */ 

/ttt Initialize accessory, graphics workstation, & register menu ttt/ 

init_acc < ) 

<. 

int x) 

/* Initialize the GEM application. If this fails, return error code. */ 

appl.init <> | 
ap_id=gl _apid; 

if <ap_id==-l> return (APP_ERR) | 

/% Initialize input array, get the physical workstation handle, 
but don't open the Virtual Screen Workstation for VDX calls. */ 

phys.handle = graf _handl e (&cel lw, Steel lh, Stchspcw, fechspch) ; 

/% get physical screen device handle tf 
work_inC 101=2} /% use Raster Coordinates */ 

work_inC03«Setrez 0+2; /* set screen device ID according to #/ 

/* resolution mode. t/ 
for (x“l| x<10; work_inCx++3=l ) ; 

/% set other input values to default %/ 

menuid = menu_regi star <ap_id, ** Sample Accessory " )) 

/* register our menu */ 

wi ..handle =* NONE) 

return<0); /* Report no errors */ 


/%%%%% Message Handler Routine ttt*/ 

handle msg ( ) /t message handler tf 

< 

long x; 

switch (msgC03) /* check message type tf 

C 

case AC_OPEN: 

if (msgC43»menuid> ft if our menu item was picked */ 

{ 

if <wi_handle =■= NONE) ft if there's no window, */ 
init_out(); /* create one */ 

/* else bring it to the front tf 
else wind.set (wi .handle, WF_TQP, 0, 0 , 0, 0); 

> 

break j 

case AC_CLOSEl 

ft if a window was open, change handle to NONE */ 

/* to show that the AES has taken it away from us */ 
i+< <flT3gE3 J= D monuid) <wi_handle 1= NONE) ) 

C 

v_cl svwk (handle) ) 
wi handle 3 NONE) 

> 

case WM_REDRAW: ft if redraw, call refresh routine t/ 

ref resh <cnsgC33 , (GRECT *)& msgC43); 
break) 

case WM_TOPPEDi ft if topped, send to top */ 

wind_set (msgC31 , WF_TOP, 0, 0, 0, 0); 
break; 
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case WM.SIZEDt ft if sized, check for min size, 

then resize t/ 

msgC63 = MAX<msgt63, cellw«8); 
msgC73 = MAX<msgC73, eellh*4>; 

wind.set (msgC33, WF.CURRXYWH, msgC43, msg[53, msgC63, msgE73); 

redraw.msg (msgC33 , (GRECT t)&msgC43); 

break; 

case WM.MOVEDj /* if moved, make sure the window 

stays on the Desktop t/ 
if (msgC43 + msgC63 > desk.g.x + desk.g_w) 
msgC43 « desk.g.x ♦ desk.g_w - msg[63; 

if (msgC53 + msgC73 > desk.g_y ♦ desk-g_h> 
msgC53 = desk.g.y desk.g.h - msgC73; 

wind.set (msgC33, WF_CURRXYWH, msgC43, msgC53, msgC63, msgC73>; 
break; 

case WM.FULLEDi /* if fulled, do toggle routine */ 

toggle (msg C 33 ) ; 
break; 

case WM.CLOSED: /* if closed, close window and 

workstation «/ 
if (msgC33 =« wi handle) 

C 

winded ose (msg C 33 ) ; 
wind.delete(msgC33 ) ; 
v.clsvwk (handle) ; 
wi handle » NONE; 

> 

break; 

defaults 

break; 

> 


/%%% Open virtual workstation, create and open output window tttf 

init outO 
t 

handle = phys.handle; 

v_opnvwk (work_in, Schandle, work_out); 

/* open virtual screen workstation %/ 
if (handle == 0) return (VWK.ERR) ; 

/* if we can't open it, return error code */ 

/% Find out the maximum size for a window, and open one. t/ 

wi nd.get (DESK, WF.WDRKXYWH, Stdesk.g.x, Scdesk.g.y, 

Scdesk.g.w, &desk.g_h); 

/* find dimensions of Desktop Window */ 
wi_handle « wind.create (WDW_CTRLS, desk.g_x, desk.g.y, 
desk . g_w, desk . g_h ) ; 

/% Create a window that size %/ 

if (wi.handle<0) 

< 

f orm.alert ( 1 , " C03 CCan' t open accessory! No windows lef t ! 3CCK3** ) ; 
v_clsvwk (handl e) j /% if we can't, close workstation */ 
return <WDW ERR); /* and return error code tf 
> 

wind_set (wi .handle, WF_ INFO, APP.INFO, 0, 0) ; 
wind_set (wi .handle, WF.NAME, APP.NAME, 0,0) ; 

ft set name and info string for window */ 
wind.open (wi .handle, desk.g.x, desk.g.y, desk.g.w/2, desk.g.h/2); 

ft open the window to quarter size tf 
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> 


ft report no errors •/ 


U 

u 


u 

u 





/%%%% routine to handle WM„FULLED message tttt/ 


toggle <wh> 
int wh; 

< 

6RECT prev, curr, full? 


ft get current, previous, 
wind_get(wh, WF_CURRXYWH, 
wind_get(wh, WF_PRBVXYWH, 
wi nd_get (wh , WF.FULLXYWH, 


and full size for window %f 
$*curr . g_x , &curr.g_y, &curr.g_w, 
&prev.g_x, &prev.g_y, &prev.g_w, 
*rfull.g_x, Scf ull . g_y, S»full.g_w, 


fccurr.g.h) ; 
8tprev.g_h) ; 
&full.g_h>; 


ft If full, change to previous (unless that was full also) tf 
if ( ( (curr.g_x =»= full.g_x> && 

(curr.g_y «« full.g_y) 

(curr.g„w =«* full.g_w) && 

(curr.g_h » full.g_h)) && 

((prev.g_x i=* full.g.x) It 
(prev.g_y !** full.g_y) S I 
<prev.g_w !«= full.g_w) II 
(prev.g h !** full.g h) ) ) 

< 

wind_set(wh, WF_GURR X YWH , prev.g_x, prev. g_y, prev.g_w, prev.g_h); 
redraw msg(wh, &prev); /* send a redraw message, cause AES won't */ 
> 


ft If not full, change to full tf 
else 

wind_set(wh, WFJCURRXYWH, full.g_x, full.g_y, full.g_w, full.g_h); 


> 


/ttttt routine to handle window_refresh (WM^REDRAW) message 
refresh(wh, drect) 

int wh; ft window handle from msgC33 */ 

GRECT tdrectj ft painter to damage rectangle tf 

i 

GRECT wrect; ft the current window rectangle in rect list */ 

graf_mause(M._OFF, 0L) ; /* turn off mouse tf 

wind_update(BEG_UPDATE) ; ft lock screen */ 

wind_get ft get first rectangle */ 

(wh, WF_FIRSTXYWH, &wrect.g_x, &wrect . g_y , &wrect.g_w, $-.wrect . g_h ) ; 


while 

if 


( wrect. g_w && wrect. g^h ) 

(overlap (drect , Scwr ect ) ) 

< 

set_cl i p ( fcwrect ) ; 
display ( ) ; 

vs_cl ip (handle, FALSE, 

> 


/* while not at last rectangle, tf 

ft check to see if this one's damaged, 

ft if it is, set clip rectangle tf 
ft redraw, and turn clip off */ 

(int t ) & wrect ) ; 


wind_get<wh, WF_NEXTXYWH, 8«wrect.g_x, &wrect.g_y, &wrect.g_w, 
Scwrect.gji) ; 


> 


*/ 


wind_update (ENDJJPDATE) ; ft unlock screen tf 

graf .mouse (h_ON, 0x0L); ft turn mouse pointer back on tf 

> 


ftttt Routine to draw the window display 
display () 

< 

int pointsC43; /* VD1 paints array */ 
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wind.get (msgC33 , WF.WORKXYWH, fcwork.g_x, fcwork.g.y, 

fcwork.g.w, &work.g_h)) /* find work area t/ 

clear.rect (fcwork) ) /% and clear it */ 


grect.conv (&wor k, ^points); /* convert work greet to array t/ 

vsf interior (handle, 2) ; /* set fill type to pattern */ 

vsf.etyle (handle, 7 t msgC33 + 2)) /* adjust fill pattern */ 
vsf .color (handle, msgE33)j /# set color */ 

v.ell ipse (handle, pointsC03 + (work.g_w/2) , pointed 3 «■ (work.g.h/2) , 
work.g_w/2, work.g_h/2)j /% draw a filled ellipse */ 


> 

/* »»»» Utility routines used by other functions «««<<<<«« •/ 




set clip (r) /S set clip to specified rectangle %/ 
BRECT tr) 

C 

int pointsC43| 

grect_conv(r, points) | 

vs cl ip (handle, TRUE, points)) 

> 


overlap (rl, r2) /» compute overlap of two rectangles «/ 

SRECT trl, tr2) 

C 

int x, y) 

x » MAX (r2->g_x , rl->g_x)| 
y » MAX (r2—>g_y, rl->g.y)| 

r2->g_w « MlN(r2->g_x + r2->g_w, rl->g_x + rl->g_w> -x j 
r2->g_h = MIN(r2->g_y + r2->g_h, r l->g_y + rl->g_h> -y| 
r2->g_x ° x | 
r2->g_y a y| 

return ( (r2->g w > 0) 8t* (r2->g_h > 0) )) 

> 


redraw.meg (wh, r) /* Send Redraw Message to your own window t/ 
int wh) 

BRECT $r ) 

int (nsgC63) 

meg C 03 = WM.REDRAW) 

msgC13 a gl_apid) 

msgC23 a 0) 

nsgC33 a wh) 

meg C 43 a r~>g_x) 

msgC33 a r->g_y) 

meg 163 a r~>g_w) 

msgC73 “ r->g_h) 

appl.write(gl_apid, 16, $cmsg>) 

> 


/t »»»»»»>»»» Some Handy Functions <<<<<<<<<<<<<<<<<< */ 
clear.rect (r ) /* clear a rectangle to the background color t/ 

brEct *rj 

< 

int pointsC43) 

vsf .interior (handle, 0) ; 
grect.conv (r , fepoints) ) 
vr.rocf 1 (handle, points) | 





n 

n 
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grect^ecnv <r t array) /• convert greet to an array of points •/ 
6RECT •r$ 
int (array; 

< 

•array-*-*- « r->g_x; 

•array-*--*- ** r— >g_y; 

•array-*-*- a r — >g_x ♦ i — >g_w - 1; 

•array = r->g y ♦ r->g h - 1; 

> 


/•••••••••ft End of Deskacc.c •••••••••*•*««••****•/ 


This program combines most of the AESSHELL.C and 
MESSAGE.C programs into one. The standard AESSHELL.C 
file could not be included this time because it opens its win- 
dow right away. In this combined file, only part of the original 
initialization routine is performed immediately. The virtual 
window and workstation are opened when the program gets 
the AC—OPEN message. Also, the cleanup routine is elimi- 
nated, since the program never ends. Instead, the 
evnt_mesage( ) routine is part of an endless loop in which 
events are received and handled. Most of the event handling 
is the same, though routines have been added to handle the 
messages AC-OPEN and AC-CLOSE, and the WM—CLOSED 
message handler has been changed to close the window and 
virtual workstation and delete the window. 

Remember that linking this program is different from a 
normal application. With the Megamax linker, the program 
command line reads 

MMLINK deskacc.c acc.l -o sample.acc 

With Alcyon C the linker command would look like the 
following: 

LINK68 [U] deskacc.68K=accstart,deskacc,vdibind,osbind,aesbind, 
libf,gemlib,libf 

Remember that the executable program must be named 
with an extender of .ACC instead of .PRG. In this case, the 
program was given the name SAMPLE.ACC. 

A machine language version of this desk accessory pro- 
gram appears below for the benefit of those who choose to 
program in that language. Since machine language programs 
contain their own startup code, that code was merely edited. 
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rather than linked with another startup file. The program be- 
low contains the startup code and, therefore, should not be 
linked with the AESSHELL.O object file. Unlike the other ma- 
chine language examples in this book, it's a complete program 
by itself. 

Program 8-2. deskacc.s 

************************************************************ 

* * 

* DESKACC.S — Assembly language version of desk * 

* accesory program, drawn from MESSAGE. S * 

* * 
************************************************************ 

*** Program equates 

aescode = Sc8 * command number for AES call 

vdicode = *73 * command number for VDI call 

*** Program starts here. Set address of our stack. 

. text 

move. I #accstk,a7 * set stack pointer to our stack 

*** Initialize the application with appl.init 





move. 1 

40,resvl 

* 

clear global variables 


move. 1 

40,resv2 




move. 1 

40,resv3 




move . 1 

40,resv4 




move 

410,ctrl0 


command » appl.init 


move 

*0, Ctrl 1 


no integer input parameters 


move 

41, Ctrl 2 


1 integer output parameter 


move 

40, Ctrl 3 


no address input parameters 


move 

40, Ctrl 4 


no address output parameters 


Jsr 

aes 


do the call 

* 

cmpi 

4SFFFF, apid i 

1 check to see if init failed 

* 

beq 

apperr 


1 and exit if it did 

*** Get the 

physical 

screen device handle from graf.handl 


move 477,ctrl0 

move #5, Ctrl 2 

Jsr aes 

move aintout 9 pwkhnd 

move aintout+2,cellw 

move aintout+4,cel lh 

move aintout+& 9 chboxw 

move aintout+8,chboxh 

move 4SFFFF 9 wd whnd 

*** Register our item on the 

move #35,ctrl0 

move #l 9 ctrll 

move 41,ctrl2 

move #1, Ctrl 3 

move apid 9 aintin 

move.l #menutxt 9 addrin 

jsr aes 

move aintout 9 menuid 

n 


* command = graf .handle 

* S integer output parameters 

* do the call 

* save handle and char sizes 


* show that no window is open 
Desk menu 

* command a menu.register 

* 1 integer input parameter 

* 1 integer output parameter 
I 1 address input parameter 

* application id 

t address of menu text item 


n 

n 

n 

n 
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ttt Main accessory loop 

ttt 

maim 


move 

#23,ctrl0 

t 

opcode =* evnt_mesage 

move 

#0,ctrl 1 



move 

•l,ctrl2 

t 

1 intout 

move 

•l,ctrl3 

t 

1 addrin 

move 

•0,ctrl4 



move. 1 

•msg, addrin 



is r 

aes 



move 

#0, Ctrl 3 



Jsr 

msghand 

t 

handle the message 

bra 

main 

t 

and loop back 


*t »»»»» End o f Main Program Code «««««««« ** 






ttt Initialize workstation and window 
ttt 

ini tout i 

ttt Open the Virtual Screen Workstation <v_opnvwk) 
move •100,contrl0 t opcode to contr 1 <0) 


move 

•0,contrl 1 

t 

no points in ptsin 

move 

•1 1 ,cantr 13 

t 

11 integers in intin 

move 

pwkhnd , contr 1 6 

t 

physical workstation handle to contr 1 

movea. 1 

«intin+2,a0 

t 

destination address 

move 

•8,d0 

t 

loop counter 

initloop* 




move.w 

•1, <a0) + 

t 

intin <1) -intin <9) =* 1 

dbra 

d0, initloop 



move 

#2, intin+20 

t 

intin(10) =» 2 (Raster Coordinates) 

move.w 

#4,-(sp) 

t 

push getrez command on stack 

trap 

• 14 

t 

call XBIOS 

addq . 1 

•2,sp 

t 

pop command off stack 

addq 

«2,d0 



move 

d0, intin 

t 

use rez+2 as device ID 

Jsr 

vdi 



move 

contrl6, vwkhnd 

t 

save virtual workstation handle 

t beq 

vwkerr 

t end program if it’s zero 

ttt Find max window size 



move 

• 104, Ctrl 0 

t 

command a wind.get 

move 

•2, Ctrl 1 

t 

2 input integers 

move 

•5,ctrl2 

t 

5 output integers 

move 

•0, aintin 

t 

window handle of Desktop 

move 

•4, aintin+2 

t 

WF_WQRKXYWH command 

jsr 

aes 



move 

ai ntout+2 , deskx 

t store desk x,y,w,h 

move 

ai ntout+4 , desky 


move 

ai ntout^, deskw 


move 

ai ntout+8, deskh 



ttt Create a window with max size 

move #100, Ctrl 0 t command » wind_create 

move #5, Ctrl 1 t 5 input integers 

move #l f ctrl2 t 1 ouput integer 

move wdwctrl , aintin t window Ctrl flag 

move deskx , aintin+2 t max x 

move desky, aintin+4 t max y 

move deskw, aintin+6 t max width 

move deskh,aintin+8 t max height 
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jsr aes 

move aintout , wdwhnd * save window handle 

* bmi wdwerr t if negative, exit program 

ttt set window name 

move 4105,ctrl0 * command « wind_set 

move 46, Ctrl 1 t 6 input integers 

move wdwhnd, aint in t window handle 

move 42,aintin+2 * subcommand « set window name 

move.l ttwdwti tl , aintin+4 t point to title 

jsr aes 


*** Open the window to 1/4 max size 


move 4101,ctrl0 * command ** wind_open 

move 4S,ctrll 

move 41, Ctrl 2 * 1 ouput integers 

move deskx , ai nt i n+2 * initial x 

move desky, ai nti n+4 * initial y 

move deskw,d0 

asr 41, d0 

move d0,aintin+6 * initial width 

move deskh,d0 

asr 41, d0 

move d0,aintin+8 * initial width 

jsr aes 

ttt Find window work area size 


move 

move 

move 

move 


4104, ctr 1 0 * 
42, Ctrl 1 * 
45, Ctrl 2 * 
44, ainti n+2 


command 53 wind_get 
2 input integers 
S ouput integers 
* WF_WORK X YWH command 


jsr aes 

move aintout +2, workx * store work x,y,w,h 

move aintout+4, worky 

move aint out +6, workw 

move aintout+B, workh 

rts 


n 

n 

□ 

n 

n 


ttt Message handler subroutine tttt 
ttt 


msghand: 





move 

msg,d5 


check message type 


cmpi 

441, dS 


AC_CLOSE? 


bgt 

msg5 


if greater, exit 


bne 

msg00 


if less, try next 


move 

msg+6,d0 


is msg<3) - menuid? 


cmp 

menuid, d0 




bne 

msgS 

t 

if not, exit 


cmpi 

44FFFF, wdwhnd 

* is window handle -1? 


beq 

msg5 

* 

if no window, exit 


move 

44FFFF, wdwhnd 

t signal that there's no 

window 

jmp 

clsvwk 

t 

close virtual workstation 

msg00s 





cmpi 

440, dS 

t 

AC_OPEN? 


bne 

msg0 

t 

if not, try next message 

type 

move 

msg+8,d0 

t 

is this our menuid? 


cmp 

menuid, d0 




bne 

msgS 


t if not, exit 


cmpi 

44FFFF, wdwhnd 

1 is no window operT? 


bne 

msg30 


* if not, move window to 

top 

imp 

ini tout 


t if so, open vwk and window 


□ 

n 

n 

n 
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msg0: 

cmpi 

beq 

cmpi 

bne 

msgl : 
move 
move 
move 
move 
move 
move 
move 
move 
Jmp 


#29, dS 
msgl: 
#27, dS 
msg2 


t WM.MOVED? 

$ if so, change size and position 
* WM.SIZED? 


#105, ctrl0 
#6, Ctrl 1 
msg+6, aintin 
#5, aintin+2 
msg+8, ai nti n+4 
msg+ 1 0 , ai nt i n+6 
msg+12, aintin+8 
msg+14,aintin+10 
aes 


t command =* wind_set 
t 6 input Integers 
t window handle 

t subcommand D set current size 


msg2: 

cmpi 

bne 


#22, dS 
msg3 


t WM CLOSED? 


ttt Close the Window 


«102,ctrl0 * 

#1 , Ctrl 1 
#1 ,ctrl2 
#0, ctrl3 
#0,ctrl4 
wdwhnd, aintin 


t command 


wind close 


ttt Delete the Window 


move 

#103, ctrl0 * 

command = wind_delete 

Jsr 

aes 


move 

#*FFFF, wdwhnd 

t turn on "no window" i 

Jmp 

clsvwk 


msg3: 



cmpi 

#21, d5 

t WM_TORRED? 

bne 

msg4 


msg30: 



move 

#105, ctrl0 

t command =* wind_set 

move 

#6, Ctrl 1 

t 6 input integers 

move 

msg+6, aintin 

t window handle 

move 

#10, aintin+2 

t subcommand = WF_TOP 

imp 

aes 


msg4: 



cmpi 

#20, d5 

t WM.REDRAW? 

bne 

msgS 


jsr 

ref resh 


msgS: 



rts 



ttt Window 

refresh subroutine ttt 

refresh: 



t turn mouse off 


move 

#79, ctrl0 t 

command =* graf_mouse 

move 

#1 , Ctrl 1 t 

1 input integers 

move 

#1 , Ctrl 2 t 

1 output integer 

move 

#256, aintin t 

hide the mouse 

jsr 

aes 



* lock screen 
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move #107,ctrl0 * command = wind_update 

move #l,ctrll * 1 input integers 

move #1, Ctrl 2 * 1 output integer 

move ttl,aintin * code =» BE5_UPDATE 

jsr aes 

* Find first window rectangle 

move #104, ctrl0 * command =* wind_get 

move #2, Ctrl 1 * 2 input integers 

move #5, Ctrl 2 * 5 ouput integers 

move msg+6, aintin * window handle 
move #11, ainti n+2 * WF.FIR5TXYWH command 

jsr aes 

refreshl: * check for empty rectangle 

move aintout+6.. dfci 

or aintout+0,d0 

beq refresh3 * if empty, at end, so quit 

move msg+8,d0 

move aintout+2, dl 

cmp d0,dl 

bcs olapl 

move d 1 , d0 

ol api: 
move 
move 
cmp 
bcs 
move 

olap2: 
move 
add 
move 
add 
cmp 
bhi 
move 

olap3: 

sub d0,d2 

move d2, aintout+6 t overlap w *= d2 - overlap x 

move msg+10,d2 I d2 = yl 

add msg+14,d2 $ + hi 

move aintout+4,d3 * d3 = y2 

add aintout+8,d3 * + h2 

cmp d2,d3 

bhi olap4 

move d3,d2 * d2 = MlN(yl+hl, y2+h2) 

olap4: 

sub dl,d2 

move d2, a intout +8 * overlap h = d2 - overlap y 

or aintout+6, d2 * are width and height both 0? 

beq refresh2 * if so, skip redraw and get next rect 

t set clip rectangle 

move #129, contrl0 t opcode for set clip <vs_clip) 

move #2,contrll * two points in ptsin 

move #0,contrl2 

move #l,contrl3 

move #0,contrl4 

move #1, intin t turn clipping on 


msg+10,dl 
aintout+4,d2 
dl ,d2 
olap2 

d2,dl * overlap y is in dl 


msg+8,d2 
msg+12, d2 
aintout+2,d3 
aintout+6, d3 
d2,d3 
ol ap3 

d3,d2 * d2 = MIN (x 1+wl , x2+w2) 


♦ x = MAX txl, x2> 

* overlap x is in d0 


n 

n 

n 


n 

n 

n 

n 

n 
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move 

d0, ptsin 

% 

pointsC03 

« overlap 

X 

add 

aintout+6,d0 





subq 

#1 , d0 

t 

pointsC2J 

« overlap 

x+w -1 

move 

d0, ptsin+4 





move 

dl , ptsin+2 

t 

pointsC 1 3 

® overlap 

y 

add 

aintout+8,dl 





subq 

#1 ,dl 





move 

dl ,ptsin+6 

* 

pointsC3J 

a overlap 

y+h -1 

Jar 

vdi 






* redraw the display 

Jsr display 

* turn clipping off 

move #129,contrl0 * opcode for set clip <vs_clip> 

move #2, contr 11 t two points in ptsin 

move #0, contr 1 2 

move #1, contr 13 

move #0, contr 14 

move 40, intin * turn clipping off 

Jsr vdi 

* get next window rectangle 
ref resh2: 

move #104,ctrl0 S command = wind_get 

move #2,ctrll * 2 input integers 

move #5, Ctrl 2 * 5 ouput integers 

move msg+6, aintin * window handle 

move #12, aintin+2 t WFJNEXTXYWH command 

Jsr aes 

bra refreshl 

* unlock screen 
refresh3: 

move #107,ctrl0 * command = wind_update 

move #l,ctrll * 1 input integers 

move #1, Ctrl 2 $ 1 output integer 

move #0, aintin * code =* END.UPDATE 

j sr aes 

* turn mouse on 

move #78, Ctrl 0 * command = graf .mouse 

move #l,ctrll t 1 input integers 

move #1, Ctrl 2 * 1 output integer 

move #257, aintin * hide the mouse 

imp aes 


ttt Window display subroutine *** 
di splay: 

t Find window work area size 

move #104, ctrl 0 t command = wind_get 

move #2, ctrl 1 * 2 input integers 

move #5, ctrl 2 * 5 ouput integers 

move msg+&, aintin 

move #4, aintin+2 * WF_WQRKXYWH command 
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j sr aes 

move aintout+2, wor kx * store work x,y,w,h 

move aintout+4, worky 

move aintout+6, workw 

move alntout+S, workh 


* set fill pattern to hollow 


move **23, contr 10 
move 4*0, contr 11 
move #0, contr 12 
move ttl, contr 13 
move ttl, contr 14 
move 4*0, intin 


* opcode for set fill type 

* one i nteger in j nt i n 

* select hollow fill type 


j sr vdi 


n 

n 

□ 

□ 

n 


* clear work area of window 


move 44114, contr 10 * 

move 4*2,ccntrll * 

move 440, contr 1 3 
move #0, contr 14 

move work>:,d0 

move d0,ptsin 

add workw, d0 

subq 44 1 f d0 

move d0,ptsin+4 
move worky, d0 

move d0,ptsin+2 
add workh, d0 

subq 4*1, d0 

move d0,ptsin+6 

jsr vdi 

* set fill type to pattern 


opcode for 
two points 


fill reciangl e 
in ptsin 


(vr_recf 1 ) 


move 4*23, contr 10 * opcode for set fill type 

move 4*0, contr 11 

move 4*1, contr 14 

move 4*2, intin t select pattern fill type 

jsr vdi 


t set type of fill pattern 


move 

4*24, contr 1 0 

move 

msg+6, d0 

mulu 

4*7, d0 

add 

4*2, d0 

move 

d0, intin 

jsr 

vdi 


* opcode for set fi 

* window number... 

* x 7 

* + 2 

* pattern type 


1 style <vsf_style> 


* set fill color 


move 

move 

addq 

move 


4*2S f contr 10 
msg+6, d0 
4*1 , d0 
d0, intin 


* opcode for set fill color <vsf_color> 
t wi ndow number ... 

* + 1 

t is color number 


jsr vdi 


t draw an ellipse 



n 

n 
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move 

*1 1 , eontrl0 

* 

opcode for 6DP 

move 

03, contrlS 

* 

sub-code for ellipse 

move 

02, contrl 1 

* 

two points in ptsin 

move 

#0, contrl 3 



move 

*0,contrl4 



move 

workw,d0 

* 

take window width 

asr 

#1 ,d0 

* 

divide in half 

move 

d0,ptsin+4 

* 

for horiz. radius of circle 

add 

workx,d0 

* 

add left x of window 

move 

d0, ptsin 

* 

for center of circle 

move 

workh,d0 

* 

take window height 

asr 

«l,d0 

* 

divide in half 

move 

d0,ptsin+6 

* 

for vert, radius of circle 

add 

worky,d0 

* 

add top y of window 

move 

d0,ptsin+2 

* 

for center of circle 

jmp 

vdi 





t t* Close Virtual Screen Workstation subroutine (v clsvwk) 

«>* 

clsvwk i 

move #101,contrl0 * opcode to contrl (0> 

move #0, contrl 1 * no points in ptsin 

move #0, contrl 3 * no integers in intin 

jmp vdi 

«t* hake AES function call 
ttt (after setting parameters) 

aes: 

move. 1 #apb,dl 
move.w #aescode,d0 
trap #2 
rts 

**« Make VDI function call 
ttt (after setting parameters) 

vdi i 

move. 1 #vpb,dl 
move . w #vd 1 code , d0 

trap #2 
rts 

ttt Storage space for program stack, AES and VDI call parameters, 
ttt and miscellaneous program variables 

• bss 
. even 

.ds.l 256 t program stack 

accstki .ds.l 1 

ttttttt*** VDI Data Arrays ************ 

contrl i 

contrl 0] . ds.w 1 

contrl 1 . ds . h 1 

contrl2i .ds.w 1 

contrl3s .ds.w 1 

contrl4: .ds.w 1 

contrlSs .ds.w 1 

contrl6: .ds.w 1 

contrl7s .ds.w 1 

contrlS: .ds.w 1 

contrl9: .ds.w 1 

contrl 10i .ds.w 1 

contrl 11: .ds.w 1 
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.ds.w 128 
.ds.w 128 
.ds.w 128 
.ds.w 128 


AES Data Arrays **************** 


.ds.w 1 
.ds.w 1 
.ds.w 1 
.ds.w 1 
.ds.w 1 


.ds.w 1 
.ds.w 1 
.ds.w 1 
. ds. 1 1 
. ds. 1 1 
. ds. 1 1 
. ds. 1 1 
.ds.l 1 


aintouti 

aintin: 

addrin: 

addrout: 


.ds.w 8 
•ds.w 18 
.ds.l 3 
.ds.l 2 


****** Misc variables 


vwkhnd .ds.w 1 
pwkhnd .ds.w 1 
wdwhnd .ds.w 1 

chboxw .ds.w 1 
chboxh .ds.w 1 
collw .ds.w 1 
cellh .ds.w 1 

deskx .ds.w 1 
desky .ds.w 1 
deskw .ds.w 1 
deskh .ds.w 1 


workx .ds.w 1 
worky .ds.w 1 
workw .ds.w 1 
workh .ds.w 1 

nsg : .ds.w 8 
menuid .ds.w 1 


* buffer for message event 


Initialized data constants 


.data 

.even 

menutxti . dc.b ' Sample Accessory 9 
wdwtitls .dc.b 'Accessory Window', 0 
wdwctrli .dc.w 43 


,0 * text of menu item 

* text of 1st window title 
* window control flag 


*** The AES and VDI parameter blocks hold pointers 
*** to the starting address of each of the data arrays 

apbi . dc . 1 Ctrl , global , aintin, aintout, addrin, addrout 
vpbi .dc.l contrl , intin, pt sin, intout, ptsout 
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Desk Accessories 


U 

U 





You should be aware of certain problems with desk acces- 
sories in the current (preblitter) version of GEM. First, 
evnt—timeri ) behaves somewhat unpredictably from a desk ac- 
cessory and may cause the program to lock up. The same is 
true of the MU—TIMER portion of evnt—multH). Also, the nor- 
mal form—do() routine has a tendency to let keystrokes "fall 
through" from the accessory to the application. This means 
that if your accessory uses a dialog box with editable text 
fields, some of the keystrokes may not reach those fields, but 
instead, they may end up being sent to the main application. 
You should consider writing your own form_do( ) in order to 
get accurate text entry from a desk accessory dialog box, at 
least with the current version of GEM on the ST. 


U 

u 

u 

u 

u 
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Appendix A 

AES Function 
Reference 




appl—init 


Initialize Application 

appl—initO Opcode =10 

This call registers the application with the AES, which then initializes sev- 
eral elements in the application's global data array. One of these contains 
the ID number which the AES assigns to the application. This ID number is 
used by other tasks, such as the GEM Screen Manager, when they wish to 
communicate with the application through its message buffer. 

C binding 

int ap-Jd; 

ap—id = appUnit( ); 

Note: As of this writing, the C bindings do not return the correct value in 
ap—id. Since this value is returned in the global variable gl-apid, the follow- 
ing work-around may be used: 

extern int gl . apid; 
int ap_Jd; 
appLJntf ); 
ap_id = gl apid; 


Inputs 



control[0] = 10 

Opcode 


controlfl] = 0 

Number of 16-bit inputs in int-Jn array 


control[2] = 1 

Number of 16-bit results in int—out array 


control[3] = 0 

Number of 32-bit inputs in addr_Jn array 

Results 

control[4] = 0 

Number of 32-bit results in addr_out 
array 

ap_id 

See also 

appl_exit( ) 

int_out[0] = 

Application ID number 
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appl— read 


Read Message Pipe 

appl— read( ) Opcode =11 

Reads a specified number of bytes from the application's message pipe. 


C binding 

int status, ap_ id, length, msgbuf[ ]; 

status = appl_read(ap_id, length, msgbuf); 


Inputs 


ap_id 

length 

msgbuf 


control 

control 

control 

control 

control 


= 11 
= 2 

- 1 
= 1 

- 0 


inLJn[0] = 


int_in[l] = 
addr_in[0] =* 


Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int— out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr_ out 
array 

ID of application whose message pipe is to 
be read (normally the application's own) 
Number of bytes to read from message 
pipe 

Address of the buffer used to store the 
bytes that are read from the message pipe 


Results 

status int_out[0] = Error status code: 

0 = an error occurred during execution 
>0 — no error occurred during execution 


See also 

appl— write( ), appl_Jnit( ) 
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appL. write 


Write to Message Pipe 

appL-write() Opcode=12 

Writes a specified number of bytes to an application's message pipe. 

C binding 

int status, ap-id, length, msgbuf[ ]; 

status = appl— write(ap_ id, length, msgbuf); 


Inputs 


ap— id 


length 

msgbuf 


control| 

control| 

control! 

control! 

control 


12 

2 

1 

1 

0 


int_in[0] = 


int_in[l] = 
addr— in[0] = 


Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int_ out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr— out 
array 

ID of application whose message pipe was 
written to (normally another application's 
ID) 

Number of bytes to written to message 
pipe 

Address of the buffer where the bytes to 
write are stored 


Results 

status int— out[0] = Error status code: 

0 = an error occurred during execution 
>0 = no error occurred during execution 


See also 

appl— read( ), appl_unit( ) 



appL- find 


Find Application ID 

appl_find() Opcode =13 

Finds the application ID number of a named application that is currently 
running in the system. The ID number may be used to establish communica- 
tions with this application, via the message pipe. 


C binding 

int id; 

char name[8]; 

id = appLJind(name); 


Inputs 


name 


Results 

ap_id 


control[0] = 13 
control[l] = 0 
control[2] = 1 
control[3] = 1 
control[4] = 0 

addr_in[0] = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

Address of text string containing the name 
of the application to be found. This text 
string must contain exactly eight text char- 
acters, followed by the NULL (ASCII 0) 
character. If the name of the application 
contains fewer than eight characters, 
spaces must be added to the end of the 
name to pad it to eight characters. 


int_out[0] = The application ID number of the applica- 
tion that was named. If the application is 
not currently loaded, — 1 is returned. 


Note; It has been reported that sometimes this function will return a valid 
ID number even after the application requested has been closed. 


See also 

appL_write( ), appLinit( ) 
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appl— tplay 


Playback Mouse and Key Macro 

appL_tplay( ) Opcode =14 

Plays a recording that has been made of the user's mouse and keyboard in- 
put. This function does not work under the current version of GEM, but 
should be fixed in future versions. 


C binding 

int actions, speed; 
char buffer[ ]; 

appl— tplay(buffer, actions, speed); 


Inputs 


actions 

speed 


buffer 


control 

control 

control 

control 

control 


14 

2 

1 

1 

0 


intiJn[0J = 
int in[l] = 


addr_ in[0] = 


Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int— out array 
Number of 32-bit inputs in addr_ in array 
Number of 32-bit results in addr_ out 
array 

The number of user actions to play back 
The speed at which to play them back, on 
a scale of 1-10,000, where 100 equals the 
original speed at which the actions were 
performed, 50 equals half speed, 200 
equals double speed, and so on. 

Address of the buffer used to store the re- 
corded user actions 


Results 


int_ out[0] = Always equals 1 


See also 

appl_trecord( ) 
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appl_trecord 


n 

n 


Record Mouse and Key Macro 

appL- trecord( ) Opcode =15 

Records a specified number of the user's mouse and keyboard input actions. 
This function does not work under the current version of GEM, but should 
be fixed in future versions. 


C binding 

int actions; 
char buffer[ ]; 

appl_trecord(buffer, actions); 


Inputs 


actions 


buffer 


Results 

recorded 


control[0 
control[l 
control[2 
control[3 
control 
int in[0] 


15 

1 

1 

1 

0 


addr__in[0] = 


Opcode 

Number of 16-bit inputs in int_Jn array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_ out array 
The number of user actions to be recorded. 
Since each action requires six bytes of stor- 
age, this number should be no greater than 
the size of the buffer divided by 6. 

The address of the buffer where the users re- 
corded actions will be stored. Each event is 
stored as six bytes. The first two bytes hold a 
16-bit event code: 

0 = timer event 

1 = mouse button event 

2 = mouse movement event 

3 = keyboard event 

The last four bytes are a 32-bit longword the 
meaning of which depends on the event: 
Timer: Time elapsed (in milliseconds) 

Mouse Button: Low word = button state 
High word = number of 
clicks 

Mouse Movement: Low word = x position 
High word = y position 
Keyboard: Low word = character typed 
High word = shift-key status 


int_out[0] = The number of events actually recorded 


See also 

appL_tplay( ) 


n 

n 

n 


n 

n 

n 

n 


n 
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appLexit 


Clean Up Application 

appl_exit( ) Opcode =19 

This function notifies the AES that the application is about to terminate, so 
that the AES can release whatever system resources are allocated to the 
application. 


C binding 

int status; 


status 

= appl— exit( ); 


Inputs 

control[0] = 19 
control[lj = 0 
control[2] = 1 
control[3] = 0 
control[4] = 0 

Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 



array 

Results 

status 

int_out[0] = 

Error status code: 

0 = an error occurred during execution 
>0 = no error occurred during execution 


See also 

appL_init( ) 
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evnt_keybd 


Wait for Keyboard Event 

evnt_Jkeybd( ) Opcode =20 

Waits for the user to press any key and returns the appropriate keycode, 

C binding 


int keycode; 
keycode = 

event— keybd( ); 


Inputs 

control[0] = 20 
control[l] = 0 
control[2] = 1 
control[3] = 0 
control[4] = 0 

Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int— out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr_ out 
array 

Results 

keycode 

int_ out[0] = 

Keycode value for the key pressed 
(See Appendix B for meaning of 
keycodes.) 

See also 
evnt_ multi( ) 





evnt_ button 


Wait for Mouse Button Event 

evnt_button( ) Opcode =21 

Waits for the user to press a particular combination of mouse buttons a spec- 
ified number of times and returns information about the mouse-button state 
and the shift-key state. 

C binding 

int clicked, clicks, bmask, bstate; 
int mousex, mousey, button, shiftkey; 

clicked = evnt_button(clicks, bmask, bstate, fcmousex, &mousey, &but- 
ton, fcshiftkey); 


Inputs 


clicks 


bmask 


bstate 


control] 

control! 

control^ 

control[3 

control 



int_in[0] = 


int_in[l] = 


int__in[2] = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int— out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr_ out 
array 

The number of clicks to wait for. To be 
more precise, the number of times that the 
mouse-button state must match the bstate 
flag within a set time period before the 
function returns. The time period is set by 
the evnt_ dclick( ) call. 

The mouse buttons for which the opera- 
tion is waiting: 

1 = left mouse button 

2 = right mouse button 

3 = both mouse buttons 

The button state for which the application 
is waiting: 

0 = both buttons up 

1 = left button down, right button up 

2 = right button down, left button up 

3 = both buttons down 


Results 

clicked 


mousex 

mousey 


int_ out[0] = The number of times the mouse-button 

state actually matched bstate. This is al- 
ways a number between 1 and the value 
stored in the variable clicks. 
int_ out[l] = The horizontal position of the mouse 

pointer at the end of the function 
int_ out[2] = The vertical position of the mouse pointer 

at the end of the function 
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evnt_ button 


button 


shiftkey 


int-_out[3] = The final mouse-button state: 

0 = both buttons up 

1 = left button down, right button up 

2 = right button down, left button up 

3 = both buttons down 

int_ out[4] = The status of the keyboard shift keys. 

Each key is represented by a different bit. 
A 1 in that bit position means that the key 
is down, while a 0 means that it's up: 


Bit Bit Value Key 

0 1 Right Shift 

1 2 Left Shift 

2 4 Control 

3 8 Alt 


See also 

evnt— multi( ) 
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evnt— mouse 


Wait for Mouse Rectangle Event 

evnt_mouse( ) Opcode = 22 

This function waits for the mouse pointer to leave or enter a particular rec- 
tangle on the display screen. 

C binding 

int reserved, mflag, rectx, recty, rectw, recth, 
mousex, mousey, button, shiftkey; 

reserved = evnt_mouse (mflag, rectx, recty, rectw, recth, &mousex, 
&mousey, &button, &shiftkey); 


Inputs 



control[0] = 22 
controlfl] = 5 
control[2] ® 5 
control[3] = 0 
control[4] = 0 

Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in inL_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

mflag 

int_in[0] = 

A code which specifies whether the call is 
waiting for the mouse pointer to enter the 
rectangle, or leave the rectangle: 

0 = waiting for mouse to enter 
rectangle 

1 = waiting for mouse to leave 
rectangle 

rectx 

int_in[l] = 

The left coordinate of the rectangle, in 
screen pixels 

recty 

int_in[2] = 

The top coordinate of the rectangle, in 
screen pixels 

rectw 

int_in[3] = 

The width of the rectangle, in screen 
pixels 

recth 

int_in[4] = 

The height of the rectangle, in screen 
pixels 

Results 

reserved 

int_out[0] = 

Reserved for future use; always equals 1 

mousex 

int_out[l] = 

The final horizontal position of the mouse 
pointer 

mousey 

int_out[2] = 

The final horizontal position of the mouse 
pointer 

button 

int_out[3] = 

The final mouse button state: 

0 = both buttons up 

1 = left button down, right button up 

2 = right button down, left button up 

3 = both buttons down 

shiftkey 

int_out[4] = 

The status of the keyboard shift keys. 

Each key is represented by a different bit. 
A 1 in that bit position means that the key 
is down, while a 0 means that it's up: 
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n 

evnt— mouse 

— =— n 


Bit Bit Value Key 

0 1 Right Shift 

1 2 Left Shift 

2 4 Control 

3 8 Alt 

See also 
evnt_multi( ) 







n 


n 

n 
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evnt— mesag 


Wait for Message Event 

evnt_mesag( ) Opcode =23 

This function waits for a standard 16-byte message to appear in the message 
pipe. When the message appears, it reads the 16 bytes into a buffer. 

Messages can be used by one task to communicate to another task, or even 
to itself. For example, the AES Screen Manager task sends standard mes- 
sages to let an application know when one of its menu items has been se- 
lected or when one of its windows needs to be redrawn. 


C binding 

int reserved, msgbuf[8]; 

reserved =* evnt_mesag(msgbuf); 


Inputs 


msgbuf 


control[0 

controlfl 

control[2 

control[3 

control[4 


= 23 
« 0 
= 1 
= 1 
= 0 


addr—in[0] = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int—out array 
Number of 32-bit inputs in addr_Jn array 
Number of 32-bit results in addr— out 
array 

The address of a 16-byte buffer in which 
the AES will store the message 


Results 

reserved int_out[0] = Reserved for future use; always equals 1 

Upon return from this function, a 16-byte message will be stored in the 
buffer pointed to by msgbuf. The general format for AES messages is 


Element 

Number Contents 

0 Message ID (indicates type of message) 

1 Application ID of message sender 

2 Number of additional bytes in message 

(in excess of the standard 16) 

3-7 Message-dependent 

There are a number of standard AES messages. The specific formats for 
these message are 


Word 

Number Contents 

0 10 (MN—SELECTED message). A menu item was selected by the 

user. 

3 The object number of the menu title that was selected. 

4 The object number of the menu item that was selected. 
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evnt_ mesag 


Word 

Number 

0 

3 

4 

5 

6 
7 

Word 

Number 

0 

3 

Word 

Number 

0 

3 

Word 

Number 

0 

3 

Word 

Number 

0 

3 

4 


Word 

Number 

0 

3 

4 


Contents 

20 (WM-JREDRAW message). A window display needs to be 
redrawn 

The handle of the window whose display needs refreshing 

The x position of the damage rectangle 

The y position of the damage rectangle 

The width of the damage rectangle 

The height of the damage rectangle 


Contents 

21 (WM_TOPPED message). The user selected a new window to 
be active. 

The handle of the window the user selected to be active 
Contents 

22 (WM—CLOSED message); The user clicked on the Close Box. 
The handle of the window whose close box was clicked 


Contents 

23 (WM—FULLED message). The user clicked on the Full Box. 
The handle of the window whose full box was clicked 


Contents 

24 (WM—ARROWED message). The user clicked on a scroll bar 
or arrow. 

The handle of the window whose scroll bar or arrow was clicked 
The action requested by the user: 

0 = page up (user clicked on scroll bar above vertical slider) 

1 = page down (user clicked on scroll bar below vertical 
slider) 

2 = line up (user clicked on up arrow) 

3 = line down (user clicked on down arrow) 

4 = page left (user clicked on scroll bar left of horizontal 
slider) 

5 = page right (user clicked on scroll bar right of horizontal 
slider) 

6 — column left (user clicked on left arrow) 

7 = column right (user clicked on right arrow) 


Contents 

25 (WM_HSLID message). The user wants to move the horizon- 
tal slider. 

The handle of the window whose horizontal slider was dragged 
The requested position for the left edge of the slider (a number 
in the range 0-1000, where 0 = far left, 1000 = far right) 


n 

n 





n 

n 
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evnt— mesag 


Word 

Number Contents 

0 26 (WM— VSLID message). The user want to move the vertical 

slider. 

3 The handle of the window whose vertical slider was dragged 

4 The requested position for the top edge of the slider (a number 
in the range 0-1000, where 0 = top, 1000 = bottom) 

Word 

Number Contents 

0 27 (WM— SIZED message). The user has dragged the Size Box. 

3 The handle of the window for which the size change is 
requested 

4 The requested x position of the window's left edge (the same as 
the current window x position) 

5 The requested y position of the window's top edge (the same as 
the current window y position) 

6 The requested width of the window 

7 The requested window height 

Word 

Number Contents 

0 28 (WM— MOVED message). The user has dragged the Move 

Bar. 

3 The handle of the window whose move bar was dragged 

4 The requested x position of the window's left edge 

5 The requested y position of the window's top edge 

6 The requested width of the window (the same as the current 

width) 

7 The requested window height (the same as the current window 
height) 

Word 

Number Contents 

0 29 (WM_NEWTOP message). A window has become active. 

3 The handle of the window that's become active 

Word 

Number Contents 

0 40 (AC_ OPEN message). A desk accessory menu has been 

selected, 

4 The menu item number (menuid) of the desk accessory the user 
selected 


Word 

Number 

0 

3 


Contents 

41 (AC-CLOSE message). An application has closed, so desk ac- 
cessories should release their window handles. 

The menu item number of the desk accessory to be closed 


u 


See also 

evnt— multi( ) 
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evnt_timer 


Wait for Timer Event 

evnt_timer( ) Opcode =24 

This functions waits for a specified number of milliseconds to pass before 
returning. 


C binding 

int reserved; 

unsigned int timelo, timehi, 

reserved = evnt_timer( timelo, timehi); 


Inputs 


timelo 

timehi 


Results 

reserved 


control 

[0] 

= 24 

Opcode 

control 

1 

= 2 

Number of 16-bit 

control 

2 

= 1 

Number of 16-bit 

control 

3 

= 0 

Number of 32-bit 

control 

4 

= 0 

Number of 32-bit 


array 

int_in[0] = Low word of the 32-bit timer value 
int-in[l] = High word of the 32-bit timer value 

Together, the low and high timer words 
form a 32-bit timer value which specifies 
the period of time the function should 
wait, in milliseconds. 


int— out[0] 


Reserved for future use; always returns a 1 


See also 

evnt— multi( ) 
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evnt— multi 


Wait for Multiple Event 

evnt_multi( ) Opcode =25 

This function allows the application to wait for multiple event types at the 
same time. The application can specify that it wishes to wait for keyboard 
events, mouse-button events, up to two mouse-rectangle events, message 
events, and/or timer events. The function returns as soon as any one of the 
specified events occurs. When the call ends, the mouse x and y position, 
mouse-button state, and shift-key state are returned, regardless of the type 
of events requested. 

C binding 

int happened, events, clicks, bmask, bstate; 
int mlflag, mlrectx, mlrecty, mlrectw, mlrecth; 
int m2flag, m2rectx, m2recty, m2rectw, m2recth; 
int msgbuf[8]; 
int timelo, timehi; 

int mousex, mousey, button, shiftkey; 
int keycode, dicker- 

happened = evnt_multi(events, dicks, bmask, bstate, mlflag, mlrectx, 
mlrecty, mlrectw, mlrecth, m2flag, m2rectx, m2recty, m2rectw, m2recth, 
msgbuf, timelo, timehi, &mousex, &mousey, &button, &shiftkey, 
&keycode, &clicked); 

Inputs 


events 


control[0] = 25 Opcode 

control[l] = 16 Number of 16-bit inputs in int_in array 
control[2] = 7 Number of 16-bit results in int_out array 
control[3] = 1 Number of 32-bit inputs in addr_in array 
control[4] = 0 Number of 32-bit results in addr_out 
array 

int_in[0] = A code which spedfies the type of event 
for which the application is waiting. Each 
event type is represented by a sin^e bit. If 
that bit is set to 1, the function will in- 
dude that event type in the list of events 
for which it is waiting. The bit values for 
the various events are 


Bit 

0 

1 

2 

3 

4 

5 


Bit Value 

Macro Name 

Event 

1 

MU_ KEYBD 

Keyboard 

2 

MU-BUTTON 

Mouse button 

4 

MU_M1 

Mouse rectangle #1 

8 

MU_ M2 

Mouse rectangle #2 

16 

MU-MESAG 

Message 

32 

MU-TIMER 

Timer 


clicks int_in[l] = The number of clicks to wait for. To be 

more predse, the number of times that the 
mouse-button state must match the state 
flag within a set time period before the 
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bmask 


bstate 


mlflag 


mlrectx 

mlrecty 

mlrectw 

mlrecth 

m2flag 


m2rectx 

m2recty 

m2rectw 

m2recth 

timelo 

timehi 


msgbuf 


int_in[2] = 


int_in[3] = 


int_in[4] = 


int_Jn[5] = 
int— in[6] = 
int_Jn[7] = 
int_Jn[8] = 
int_in[9] = 


int_Jn[10] = 

int_in[ll] = 

int_in[12] = 

int_in[13] = 

int_in[14] = 
ini_in[15] = 


addr_in[0] = 


function returns. The time period is set by 
the evnt— dclick( ) call. 

The mouse buttons for which the applica- 
tion is waiting: 

1 = left mouse button 

2 = right mouse button 

3 = both mouse buttons 

The button state for which the application 
is waiting: 

0 = both buttons up 

1 = left button down, right button up 

2 = right button down, left button up 

3 = both buttons down 

A code which specifies whether the call is 
waiting for the mouse pointer to enter or 
leave the first mouse rectangle: 

0 = waiting for mouse to enter 
rectangle 

1 = waiting for mouse to leave 
rectangle 

The left coordinate of the first mouse rec- 
tangle, in screen pixels 
The top coordinate of the first mouse rec- 
tangle, in screen pixels 
The width of the first mouse rectangle, in 
screen pixels 

The height of the first mouse rectangle, in 
screen pixels 

A code which specifies whether the call is 
waiting for the mouse pointer to enter or 
leave the second mouse rectangle: 

0 = waiting for mouse to enter 
rectangle 

1 = waiting for mouse to leave 
rectangle 

The left coordinate of the second mouse 

rectangle, in screen pixels 

The top coordinate of the second mouse 

rectangle, in screen pixels 

The width of the second mouse rectangle, 

in screen pixels 

The height of the rectangle, second mouse 
in screen pixels 

Low word of the 32-bit timer value 
High word of the 32-bit timer value 
Together, the low and high timer words 
form a 32-bit timer value which specifies 
the period of time the function should 
wait, in milliseconds. 

The address of a 16-byte buffer in which 
the AES will store the message 
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Results 

happened 

int_out[0] = 

A code which specifies the type of event 
which actually happened. The code used 
is identical to that used for events above. 

mousex 

int__out[l] = 

The final horizontal position of the mouse 
pointer 

mousey 

int_out[2] — 

The final vertical position of the mouse 
pointer 

button 

int_out[3] = 

The final mouse-button state: 

0 = both buttons up 

1 = left button down, right button up 

2 *=» right button down, left button up 

3 = both buttons down 

shiftkey 

int_out[4] = 

The status of the keyboard shift keys. 

Each key is represented by a different bit. 
A 1 in that bit position means that the key 
is down, while a 0 means that it's up: 

Bit Bit Value Key 


0 1 

Right Shift 


1 2 

Left Shift 


2 4 

Control 


3 8 

Alt 


keycode 

int_out[5] = 

The code number for the key combination 
pressed by the user. See Appendix B for a 
complete list of keycodes. 

clicked 

int_out[6] = 

The number of times the mouse-button 
state actually matched bstate. This is al- 
ways a number between 1 and the value 
stored in the variable clicks. 

See also 

evnt_keybd( ), evnt_button( ), 

evnt__mouse( ), evnt_mesag( ), evnt_timer( ) 
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evnt— dclick 


Set Double-Click Speed 

evnt_dclick( ) Opcode =26 

Reads the current setting of the double-click interval (the amount of time 
which a mouse button event will wait for multiple clicks) or changes that 
setting. 

C binding 

int speed_set, speed, flag; 

speecLset = evnt_dclick(speed, flag); 


Inputs 



controlJO] = 26 
control[l] = 2 
control[2] = 1 
control[3] = 0 
control[4] = 0 

Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_ out 

speed 

intJn[0] = 

array 

The new double-click speed. A number in 
the range 0-4, where 0 is the slowest 
speed and 4 the fastest speed. 

flag 

int_in[l] = 

A code which specifies whether you wish 
to read the current setting or to change it: 

0 = set a new speed 

1 = read the current speed 

Results 

speed_set 

See also 

evnt_mouse( ), 

int_out[0] = 
evnt_multi( ) 

The existing or new double-click setting 




u 

u 




u 

u 

u 

u 


menu— bar 


Display or Erase Menu Bar 

menu_bar( ) Opcode =30 

This function is used to display an application's menu bar or to erase that 
menu bar. The menu erase function should always be used before changing 
menu bars and before the appl_exit( ) call made prior to exiting the 
program. 

C binding 

int status, showflag; 

OBJECT *tree; 

status = menu— bar( tree, showflag); 

Inputs 

Opcode 

Number of 16-bit inputs in int_Jn array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

A code which determines whether this call 
causes the menu bar to be displayed or 
erased: 

0 = erase the menu bar 

1 = display the menu bar 
The address of the object tree array which 
supplies the data for the menu display 


Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


showflag 


control| 

controlj 

controlj 

controlj 

control 


= 30 
= 1 
= 1 
= 1 
= 0 


int_in[0] = 


tree 


addr_ in[0] = 


Results 

status 


int— out[0] = 
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Display or Erase Checkmark 

menu_icheck( ) Opcode =31 

Displays a checkmark in front of a menu item or erases the checkmark. 


C binding 

int status, item, setting; 
OBJECT *tree; 


status 

Inputs 

= menu_icheck(tree, item, setting); 
control[0] = 31 Opcode 

controlfl] = 2 Number of 16-bit inputs in int_in array 

control[2] = 1 Number of 16-bit results in int_out array 

control[3] = 1 Number of 32-bit inputs in addr_in array 

control[4] = 0 Number of 32-bit results in addr_out 

array 

item 

int_in[0] = 

The object number of the menu item 

setting 

int_in[l] = 

A code indicating whether the specified 
item should be checked or have its check- 
mark erased: 

0 *** erase a checkmark, if visible 

1 = display a checkmark in front of 
the item 

tree 

addr_in[0] = 

The address of the object tree array which 
supplies the data for the menu display 

Results 

status 

int—out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

appL_exit( ) 
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Enable or Disable Menu Item 

menu— ienable( ) Opcode =32 

Disables the selection of a menu item or enables its selection. When the 
menu item is disabled, its text is "grayed out," that is, printed in faint 
characters. 


C binding 

int status, item, setting; 

OBJECT *tree; 

status = menu— ienable(tree, item, setting); 


Inputs 


item 

setting 


tree 


control[0] = 32 
controlfl] = 2 
control[2] = 1 
control[3] = 1 
control[4] = 0 

int— in[0] = 

int_ in[l] = 


addr_ in[0] = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_ out array 
Number of 32-bit inputs in addr_ in array 
Number of 32-bit results in addr_ out 
array 

The object number of the item to be dis-* 
abled or enabled 

A code which indicates whether selection 
of the menu item is to be disabled or 
enabled: 

0 = selection of the menu item is 
disabled 

1 = selection of the menu item is 
enabled 

The address of the object tree array which 
supplies the data for the menu display 


Results 

status int_ out[0] — Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 



menu— (normal 


Toggle Menu Title Highlight 

menu— tnormal( ) Opcode =33 

This function either displays a menu title in normal video or highlights it in 
reverse video. It is most often used to return a menu title to normal video 
after the program has carried out an action in response to the selection of a 
menu item. 

C binding 

int status, title, setting; 

OBJECT *tree; 

status = menu— tnormal(tree, title, setting); 

Inputs 



control] 

[0] 

| = 33 Opcode 


control| 

1 

= 2 

Number of 16-bit inputs in int-in array 


controlj 

2 

= 1 

Number of 16-bit results in int— out array 


control 

3 

= 1 

Number of 32-bit inputs in addr— in array 

to 

control! 

4 

= 0 

Number of 32-bit results in addr— out 
array 

title 

int in[0] 


The object number of the menu title 
which is to be displayed normally or 
highlighted 

setting 

int-in[l] 


A code which indicates whether the menu 
title should be highlighted in reverse 
video, or displayed in normal video: 

0 = display in reverse video 

1 = display in normal video 

tree 

addr— in[0] 5=8 

The address of the object tree array which 
supplies the data for the menu display 

Results 

status 

int_out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 
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Change Menu Item Text 

menu_text( ) Opcode =34 

Changes the text of a menu item. This allows menu selections to change in 
response to changes in the program context. 

C binding 

int status, item; 
char *text; 

OBJECT *tree; 

status = menu— text(tree, item, text); 


Inputs 



control[0] = 34 
control[lj = 1 
control[2] = 1 
control[3] = 2 
control[4] = 0 

Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

item 

int_in[0] = 

The object number of the menu items 
whose text will be replaced 

tree 

addr_in[0] = 

The address of the object tree array which 
supplies the data for the menu display 

text 

addr_in[l] = 

The address of the new text string to be 
used for the menu item. The text string 
should end in the NULL character (ASCII 
0) and should be no longer than the string 
which it replaces. 

Results 

status 

int_out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 — no error occurred during 
execution 



menu— register 


Add Item to Desk Menu 

menu— register( ) Opcode =35 

This function allows a desk accessory to add an item to the DESK menu. A 
single accessory may add more than one item to the menu, but all acces- 
sories may only use a total of six menu items. 

C binding 

extern int g!_apid; 

int menuid; 

static char *menutext; 

menuid = menu— register(gl— apid, menutext) 


Inputs 


gLapid 


menutext 


control] 

controlj 

controlj 

control! 

control 


35 

1 

1 

1 

0 


int-in[0] = 


addr_in[0] = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int—out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr— out 
array 

The application ID number. This value 
should be returned by appLinit( ), but 
currently the bindings only place it in the 
global variable gl—apid. 

The starting address of the null-terminated 
text string used for the menu item 


Results 

menuid int— out[0] = The desk accessory's menu ID number. 

Valid ID numbers in the range 0-5. An ID 
number of —1 means that there is no 
room on the menu for this item. 



objc— add 


Add an Object to a Tree 

objc_add( ) Opcode = 40 

Adds an object to an object tree, by linking it in with the parent object and 
other sibling objects, if any. This function is not normally used by the appli- 
cations programmer if a resource construction program is used to create the 
object trees. 


binding 

int status, parent, child; 
struct object tree[ ]; 


status 

= objc_add(tree, parent, child); 

nputs 


control| 

[0] = 40 

Opcode 


controlj 

1] = 2 

Number of 16-bit inputs in int_in array 


controlj 

2] = 1 

Number of 16-bit results in int_out array 


controlj 

3] = 1 

Number of 32-bit inputs in addr_in array 


controlj 

4] = 0 

Number of 32-bit results in addr_out 
array 

parent 

int_Jn[0] = 

The object number of the parent to which 
a child object will be added 

child 

int_in[l] = 

The object number of the child object to 
be added 

tree 

addr_in[0] = 

The address of the object tree array which 
contains the .objects 

Results 

status 

int_out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

objc_delete( ) 



objc— delete 


Delete an Object from a Tree 

objc— delete( ) Opcode =41 

Deletes a child object from an object tree by unlinking it from its parent ob- 
ject and sibling objects, if any. This function is not normally used by the 
applications programmer if a resource construction program is used to create 
the object trees. 

C binding 

int status, object; 
struct object tree[ ]; 

status = objc_delete(tree, object); 


Inputs 


object 

tree 


control] 

control] 

control| 

controlj 

control 



int_in[0] = 


addr_in[0] = 


Opcode 

Number of 16-bit inputs in inti_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

The object number of the object to be 
deleted 

The address of the object tree array which 
contains the objects 


Results 

status 


int_out[0] — Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

objc_add( ) 
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U 

U 

U 


u 

u 

u 


Draw an Object Tree 

objc_draw( ) Opcode =42 

This function draws all objects in an entire object tree or in any branch of 
the tree. It also allows the specification of a clipping rectangle and will only 
draw those objects which fall within the rectangle. 

C binding 

int status, firstob, depth, clipx, clipy, clipw, cliph; 
struct object tree[ ]; 

status = objc__draw(tree, firstob, depth, clipx, clipy, clipw, cliph); 


Inputs 


control 

[0] 

- 42 

Opcode 


control 

1 

= 6 

Number of 16-bit inputs in int_Jn array 


control 

2 

= 1 

Number of 16-bit results in int_out array 


control 

3 

= 1 

Number of 32-bit inputs in addr_in array 


control 

4 

= 0 

Number of 32-bit results in addr_out 
array 

firstob 

int_Jn[0] 


The object number of the first object in 
the tree to be drawn. All descendants of 
this object will be drawn as well. 

depth 

int_in[l] 


The number of levels of descent from the 
original object to draw. The object itself is 
zero levels down, its immediate children 
are one level down, their children are two 
levels down, and so on. 

clipx 

int_Jn[2] 

= 

The horizontal coordinate for the left side 
of the clipping rectangle 

clipy 

int_in[3] 

= 

The vertical coordinate for the top edge of 
the clipping rectangle 

clipw 

int_in[4] 

== 

The width of the clipping rectangle, in 
screen pixels 

cliph 

int_in[5] 

= 

The height of the clipping rectangle, in 
screen pixels 

tree 

addr_in[0] = 

The address of the object tree array which 
contains the objects 

Results 

status 

int_out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


u 

u 


251 



objc— find 


Find Objects Under Mouse Pointer 

objc_f!nd( ) Opcode = 43 

Finds the topmost object that covers a particular point on the screen, usually 
the spot occupied by the mouse pointer. 

C binding 

int foundob, firstob, depth, x, y; 
struct object tree[ ]; 

foundob = objc_find(tree, firstob, depth, x, y); 


Inputs 


firstob 


Results 

foundob 


See also 

wind_iind( ) 


control[0] 

control[l] 

control[2] 

control[3] 

control[4] 

int in[0] = 


int— in[l] 


int_Jn[2] = 
int_in[3] = 
addr_in[0] - 


int_out[0] = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int— out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr_out 
array 

The object number of the first object in 
the tree to be searched. All descendants of 
this object will be searched as well. 

The number of levels of descent from the 
original object to search. The object itself 
is zero levels down, its immediate children 
are one level down, their children are two 
levels down, and so on. 

The horizontal screen coordinate of the 
point to be searched 

The vertical screen coordinate of the point 
to be searched 

The address of the object tree array which 
contains the objects 


The object number of the object found at 
the designated screen location. If no object 
was found there, — 1 is returned 
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Find Object’s Screen Position 

objc_ offset( ) Opcode =44 

This function calculates the absolute screen position of an object. This func- 
tion is needed because each object's position is stored internally as an offset 
relative to that of its parent object. 

C binding 

int status, object, x, y; 
struct object tree[ ]; 

status = objc_ offset(tree, object, &x, &y); 


Inputs 



control[0] = 44 
control[l] = 1 
control[2] = 3 
control[3] = 1 
control[4] = 0 

Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

object 

int_in[0] = 

The object whose screen location you wish 
to find 

tree 

addr_in[0] = 

The address of the object tree array which 
contains the object 

Results 

status 

int_out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 

X 

int_out[l] = 

The horizontal screen position of the ob- 
ject, in pixels 

y 

int_out[2] = 

The vertical screen position of the object 
in pixels 
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Reorder Child Objects 

objc_ order( ) Opcode =45 

Moves a child object to a new position, relative to its siblings. 


C binding 

int status, object, newpos; 
struct object tree[ ]; 

status = objc— order(tree, object, newpos); 


Inputs 


object 

newpos 


tree 


control 

control 

control 

control 

control 


[ 0 ] 

1 

2 

3 

4 


45 

2 

1 

1 

0 


int— in[0] = 


int — in[l] = 


addr_ in[0] = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr— out 
array 

The object number of the child to be 
moved 

A code specifying the new position at 
which to place the object: 

— 1 = on top 

0 = on the bottom 

1 = one from the bottom 

2 = two from the bottom (and so on) 
The address of the object tree array which 
contains the objects 


Results 

status int— out[0] = Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

objc_ add( ), objc— delete( ) 



objc— edit 


Let User Edit Text Objects 

objc— edit( ) Opcode =46 

This function allows the user to edit the text that appears in a G_ FTEXT or 
G—FBOXTEXT object. It is used by the AES as part of the form_do( ) call 
and is not ordinarily a function that would be used unless the application 
programmer was writing his or her own version of form— do( ). 


C binding 

int status, object, char, index, type; 
struct object tree[ ]; 

status = objc_edit(tree, object, char, &index, type); 

Note: This binding varies from the format specified by the Digital Research 
documentation, which adds a parameter for the ending index to the end of 
the parameter list. The binding shown above, however, is the one actually 
supplied by Atari with the Alcyort C compiler and all compilers whose 
bindings derive from Atari's. 


Inputs 



control[0] = 46 
controlfl] = 4 
controI[2] = 2 
control[3] = 1 
control[4] = 0 

Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

object 

int— in[0] = 

The object number of the editable text 
object 

char 

int_in[l] = 

The text character entered by the user 

index 

inL_in[2] = 

The position of the next character to be 
entered in the text string (cursor position) 

type 

inL_in[3] = 

A code specifying the type of operation to 
perform. Valid code numbers include the 
following: 


Type Macro 
Number Name 

0 ED— START 

1 ED—INIT 


2 ED_CHAR 


3 ED-END 


Description of Function 
Reserved for future use 

Combine the template string of TEDINFO field 
te_ptmplt with the text string of the te_ptext field 
to display the formatted string and then turn the 
cursor on. 

Check the input character against the validation 
string in TEDINFO field te_pvalid, update the 
te_ptext field if the input character is valid, and 
display the changed text. 

Turn off the text cursor. 


tree addr_in[0] = The address of the object tree array which 

contains the objects 
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objc— edit 


Results 

status 


index 


See also 

form_do( ) 


int_out[0] = 


int_out[0] = 


Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 

The new position of the next character to 
be entered in the text string (cursor posi- 
tion) after objc_edit( ) has been performed 



objc— change 


Change Object’s State Flag 

objc_change( ) Opcode =47 

This function is used to change an object's ob— state flag. Since this change 
may affect the object's appearance on screen, the function allows the pro- 
grammer to request a redraw of the object when its state is changed. A clip- 
ping rectangle may also be specified, and only objects within this rectangle 
are redrawn. 


C binding 

int status, object, reserved, clipx, clipy, clipw, diph, state, redraw; 
struct object tree[ ]; 

status = objc— change(tree, object, reserved, clipx, clipy, clipw, cliph, 
state, redraw); 


Inputs 



^OOHHO 

(1 II (1 II II 

© 1-H cm en T* 

mu 

c g c c e 

8 8 8 8 8 

Opcode 

Number of 16-bit inputs in int—in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 

object 

int_Jn[0] = 

array 

The object number of the object whose 
state flag is to be changed 

reserved 

int_in[l] = 

Reserved for future use; must always be 0 

clipx 

int_in[2] = 

The horizontal coordinate for the left side 
of the clipping rectangle 

clipy 

int_in[3] — 

The vertical coordinate for the top edge of 
the clipping rectangle 

clipw 

int_Jn[4] = 

The width of the clipping rectangle, in 
screen pixels 

cliph 

int_in[5] = 

The height of the clipping rectangle, in 
screen pixels 

state 

int_Jn[6] = 

The new value for the object's ob— state 
flag 

A code which specifies whether or not the 
object should be redrawn after the state 
change: 

0 = no redraw of the object 

1 = the object is redrawn 

redraw 

int_Jn[7] = 

tree 

addr_Jn[0] = 

The address of the object tree array which 
contains the objects 


Results 

status int_out[0] = Error status code: 

0 * an error occurred during 
execution 

>0 = no error occurred during 
execution 
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Handle Dialog 

forai— do( ) Opcode = 50 

Form_do( ) is like a small subprogram that monitors the user's interaction 
with a dialog box. It handles the selection of objects with the left mouse but- 
ton and also handles the entry of text into the editable text objects. Since 
form— do( ) itself calls evnt_multi( ), it takes control of all event waiting. 

This means that menus do not function while form— do( ) is executing. 

C binding 

int exitobj, editobj; 

OBJECT *tree; 

exitobj = form— do(tree / editobj); 


Inputs 



control 

[0 

- 50 

Opcode 


control 

1 

= 1 

Number of 16-bit inputs in int— in array 


control 

2 

= 1 

Number of 16-bit results in int— out array 


control 

3 

= 1 

Number of 32-bit inputs in addr_in array 


control 

4 

= 0 

Number of 32-bit results in addr_ out 
array 

editobj 

int— in[0] 


The object number of the editable text 
field at which the cursor should be posi- 
tioned when the dialog is initially dis- 
played. If there aren't any editable text 
fields in the dialog, the number 0 should 
be used. 

tree 

addr_in[0] = 

The address of the object tree array which 
is used to draw the dialog 

Results 

exitobj 

int_out[0] = 

The object number of the object whose se- 
lection caused the dialog to terminate. If a 
TOUCHEXIT object was double-clicked, 
the high bit of this value will be set. 


See also 

form_button( ), form_keybd( ), objc_ edit( ), evnt— multi( ) 
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Begin or End Dialog 

form— dial( ) Opcode =51 

This function can be used to reserve a portion of the screen for the dialog 
box, to release that portion of the screen, and to draw an expanding box 
before the dialog opens, and a contracting one after it finishes. 


C binding 

int status, type, smallx, smally, smallw, smallh; 
int largex, largey, largew, largeh; 

status = form— dial(type, smallx, smally, smallw, smallh, largex, largey, 
largew, largeh); 

Note: This binding varies from the one described in the Digital Research 
documentation, which omits the rectangle information for the second rectan- 
gle. The binding shown above, however, conforms to the format actually 
used in Alcyott C bindings supplied by Atari and all bindings that derive 
from them (such as those used by Megamax C). 


Inputs 


type 


control 

[0] 

= 51 

control 

1 

= 9 

control 

2 

= 1 

control 

3 

- 0 

control 

4 

= 0 

int_in[0] 

= 


Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int-out array 
Number of 32-bit inputs in addr_ in array 
Number of 32-bit results in addr— out 
array 

A code which specifies the type of action 
to take: 


Type 

Macro 


Number 

Name 

Action 

0 

FMD—START 

Reserves the screen area used by the dialog 
box 

1 

FMD—GROW 

Draws expanding box from small to large 
rectangle 

2 

FMD_SHRINK 

Draws shrinking box from large to small 
rectangle 

3 

FMD— FINISH 

Frees the screen area used by the dialog box 
and causes redraw messages to be sent 

smallx 

int_in[l] = 

The horizontal coordinate of the left edge 
of the smaller rectangle 

smally 

int_in[2] = 

The vertical coordinate of the top edge of 
the smaller rectangle 

smallw 

int_in[3] = 

The width of the smaller rectangle, in 
screen pixels 

smallw 

int_ in[4] = 

The height of the smaller rectangle, in 
screen pixels 

largex 

int_ in[5] = 

The horizontal coordinate of the left edge 
of the larger rectangle 

largey 

int_in[6] = 

The vertical coordinate of the top edge of 
the larger rectangle 
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largew 

int_in[7] = 

The width of the larger rectangle, in 
screen pixels 

largeh 

int_ in[8] = 

The height of the larger rectangle, in 
screen pixels 

Results 

status 

int_out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

form_do( ) 



form-alert 


Display an Alert Box 

form— alert( ) Opcode = 52 


Displays an alert box and returns the user's response to the alert. 

C binding 

int exitbutn, default- 
char ^string; 

exitbutn = form— alert(default, string); 


Inputs 


default 


string 


control[0] = 52 
control[lj = 1 
control[2] = 1 
control[3] = 1 
control[4] = 0 

int — in[0] = 


addr— in[0] — 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_ out 
array 

The default exit button, which will be se- 
lected if the user presses the Return key: 

0 = no default exit button 

1 = first exit button 

2 = second exit button 

3 = third exit button 

The address of the null-terminated string 
containing the alert text. The format for 
this string is 


[Icon_number][Message text][Exit button text] 

This string is separated into three parts, each set off by square brackets. 
The first item, icon— number, is a single numeric digit indicating which image 
(if any) should be displayed at the left side of the alert box. The choices are 


Icon 

Number 

Image 

Meaning 

0 

None 


1 

Exclamation point in diamond 

Note 

2 

Question mark in yield-sign triangle 

Wait 

3 

Octagonal stop sign 

Stop 


The second set of square brackets holds the text message. This message 
is limited to a maximum of five lines, each of which may contain a maxi- 
mum of 40 characters. The vertical bar character ( I ) is used to indicate the 
start of a new line. 

The final set of square brackets contains the text for the exit buttons. A 
maximum of three exit buttons may be used, each of which contains a maxi- 
mum of 20 characters of text. The text for each button is separated with a 
vertical bar character. 
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form— alert 


Results 

exitbutn 


int_out[0] = The exit button selected by the user: 

1 = first exit button 

2 = second exit button 

3 = third exit button 
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form_error 


U 

u 

Li 


U 

u 

u 

u 

u 


Display an Error Box 

form_error() Opcode =53 

Displays an error box, which informs the user of a TOS error. 

C binding 

int exitbutn, error; 

exitbutn = form— error(error); 

Inputs 

control[0] = 53 Opcode 

controlf 1] — 1 Number of 16-bit inputs in int__in array 

control[2] = 1 Number of 16-bit results in int— out array 

control[3] = 0 Number of 32-bit inputs in addr— in array 

control[4] = 0 Number of 32-bit results in addr— out 

array 

error int— in[0] = The TOS error code. Actually, since GEM 

was designed with IBM PC-DOS in mind, 
this routine expects to get PC-DOS error 
codes, rather than the GEMDOS error 
codes returned on the Atari ST computers. 
In order for form— error( ) to print out its 
error messages correctly, you must convert 
the GEMDOS codes to PC codes. This is 
done by reversing the sign of the code 
from negative to positive, and then sub- 
tracting 31 (DOS-ERR = (—TOS— ERR) 

— 31). The following chart lists the 
GEMDOS error codes for which 
form_error( ) prints error-specific mes- 
sages messages (as opposed to TOS error 
#X) and gives the complete text of those 


GEMDOS 

Error 

PC-DOS 

Error 

messages. 


Number 

Number 

Error 

form— error( ) Message 

-33 

2 

File not found 

This application can't find 
the folder or file you just 
tried to access. 

-34 

3 

Path not found 

This application can't find 
the folder or file you just 
tried to access. 

-35 

4 

File handle pool ex- 
hausted (no file 
handles left) 

This application doesn't 
have room to open another 
document. To make room, 


close any document that 
you don't need. 
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GEMDOS 

Error 

Number 

-36 

-39 

-41 

-42 

-46 

-47 

-49 

Results 

exitbutn 




PC-DOS 

Error 



Number 

Error 

form-_error( ) Message 

5 

Access denied (wrong 
attribute or access 
code) 

An item with this name al- 
ready exists in the directory, 
or this item is set to Read- 
only status. 

8 

Insufficient memory 

There isn't enough memory 
in your computer for the 
application you just tried to 
run. 

10 

Invalid environment 

There isn't enough memory 
in your computer for the 
application you just tried to 
run. 

11 

Invalid format 

There isn't enough memory 
in your computer for the 
application you just tried to 
run. 

15 

Invalid drive 
specification 

The drive you specified 
does not exist. Check the 
drive's identifier or change 
the drive identifier in the 
DISK INFORMATION 
dialog. 

16 

Attempted to remove 
the current directory 

You cannot delete the 
folder in which you are 
working. 

18 

No more files 

This application can't find 
the folder or file you just 
tried to access. 


□ 

□ 

□ 


int_out[0] *=* The exit button that the user selected. 

Since the current version of GEM on the p“| 

ST only displays one button, this number | t 

isn't significant. 


n 

□ 

n 

n 
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Center the Dialog Box 

form_center( ) Opcode =54 

Changes the x and y coordinates of the root object in a dialog tree, so that 
the dialog box is centered onscreen. The function also returns the position 
and size information for the centered dialog. 

C binding 

int x, y, width, height; 

OBJECT *tree; 

reserved = form_center(tree, &x, &y, fcwidth, &height); 


Inputs 



control[0] = 54 
control[l] = 0 
control[2] = 5 
control[3] = 1 
control[4] = 0 

Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

tree 

addr_in[0] = 

The address of the object tree array which 
makes up the dialog box 

Results 

reserved 

int_out[0] = 

Reserved for future use; always equals 1 

X 

int_out[l] = 

The horizontal coordinate of the left edge 
of the centered dialog rectangle 

y 

int_o'ut[2] = 

The vertical coordinate of the top edge of 
the centered dialog rectangle 

width 

int_out[3] = 

The width of the centered dialog rectan- 
gle, in screen pixels 

height 

int_out[4] = 

The height of the centered dialog rectan- 
gle, in screen pixels 


u 

u 

u 

u 

u 
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form— keybd 


n 

n 


Handle form_do( ) Events 

form_keybd( ) Opcode =55 

This is the routine form— do( ) calls after its evnt_multi( ) call detects a 
keypress. If this routine detects a control key like the Tab or Up Arrow, it 
select the next editable text object. If it detects the Return key, it selects the 
DEFAULT object. Otherwise, it filters the keystroke and passes the printing 
key back to the calling routine. Since it is such a limited subset of 
form— do( ) functions, it is of interest mainly to programmers writing their 
own form— do( ) routine. 

C binding 

There is no official C binding for this routine. Therefore, if you wish to call 
it from C, you must either write a machine language function to call it, write 
your own bindings, or place the correct values into the global arrays directly 
and then call the crys— if(55) function which is in the regular bindings. If 
you choose either of the latter two, you must also change the values in entry 
55 of the Ctrl— cnts array (which is in the regular bindings, in the file 
GEMSTART.S for the Alcyon compiler) to 

.dc.b 3,3,1 * func 55 


Inputs 



control[0] = 55 

Opcode 


control[l] = 3 

Number of 16-bit inputs in int-in array 


control[2] = 3 

Number of 16-bit results in int— out array 


control(3] = 1 

Number of 32-bit inputs in addr— in array 


control[4] — 0 

Number of 32-bit results in addr— out 
array 

edit— obj 

int— in[0] = 

Number of the text object currently being 
edited 

next— obj 

int— in[l] = 

Flag for change in edited object number 

keyin 

int— in[2J = 

Keycode received from evnt— multi 

tree 

addr— in[0] - 

The address of the object tree array which 
makes up the dialog box 

Results 


int— out| 

0] = 

continue 


int— out 

1] = 

obj— out 


int— out 

2] = 

keyout 

continue 

int_out 

0] = 

Flag for exit object selection 

0 = exit object selected 

1 = exit object not selected, continue 

obj— out 

int_out[l] = 

Number of new edit object 

keyout 

See also 

int_out[2] = 

Processed keycode. A 0 indicates that this 
function has handled it, and no further 
processing is required for this key. 

form— do( ), form— butn( ) 




n 

n 


n 

n 

n 

n 
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form_butn 


Handle form_do( ) Mouse Events 

form_butn( ) Opcode =56 

This function is called by form_do( ) when its evnt_multi( ) call detects a 
mouse-button press. First, objc_find( ) is used to locate the object. Then 
form_butn( ) is called. This routine highlights the object if it's SELECTABLE 
and not DISABLED and performs the deselect function for radio buttons. It 
sets an exit flag for EXIT or TOUCHEXIT objects. If the object was EDIT- 
ABLE, it returns the initial object number and, if not, it zeros it out so that 
form— do( ) won't change the object. Since this is such a limited subset of 
form— do( ) functions, it's of interest mainly to programmers writing their 
own form— do( ) routine. 

C binding 

There is no official C binding for this routine. Therefore, if you wish to call 
it from C, you must either write a machine language function to call it, write 
your own bindings, or place the correct values into the global arrays directly 
and then call the crys_ if (5 6) function, which can be found in the regular 
bindings. If you choose either of the latter two, you must also change the 
values in entry 56 of the Ctrl— cnts array (which is in the regular bindings, in 
the file GEMSTART.S for the Alcyon compiler) to 


.dc.b 2,2,1 

• func 56 


Inputs 


control[0] = 56 

Opcode 


controlfl] = 2 

Number of 16-bit inputs in int_in array 


control[2] = 2 

Number of 16-bit results in int— out array 


control[3] = 1 

Number of 32-bit inputs in addr_ in array 


control[4] = 0 

Number of 32-bit results in addr_ out 
array 

object 

int_ in[0] = 

Number of the object clicked on 

clicks 

int_in[l] = 

Number of mouse-button clicks received 
from evnt_multi( ) 

tree 

addr_ in[0] — 

The address of the object tree array which 
makes up the dialog box 

Results 

continue 

int_out[0] = 

Flag for exit object selection 

0 = exit object selected 

1 = exit object not selected, continue 

obj_out 

int— out[l] = 

Number of the new edit object 

See also 

form— do, form— keybd( ) 
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Draw a Rubber Box 

graf_rubberbox( ) Opcode =70 

This function draws a dotted box outline on the screen, the upper left comer 
of which is fixed, but the lower right portion of which follows the mouse 
pointer so long as the user holds down the left mouse button. When the left 
mouse button is released, the function ends, and the box is erased. This func- 
tion should only be called when the program has determined that the left 
mouse button is already down, by returns from form_do( ), evnt_multi( ), or 
evnt_button( ), since if it is up, the function will end as soon as it's called. 

C binding 

int status, x, y, minw, minh, endw, endh; 

status = graL_rubberbox(x, y, minw, minh, &endw, &endh); 


Inputs 



control[0 

control[l 

control[2 

control[3 

control[4 

= 70 Opcode 

— 4 Number of 16-bit inputs in intJn array 

= 3 Number of 16-bit results in int_out array 

= 0 Number of 32-bit inputs in addr_Jn array 

= 0 Number of 32-bit results in addr— out 

array 

x 

int_in[0] 


The horizontal screen coordinate of the 
left edge of the box 

y 

int—in[l] 

= 

The vertical screen coordinate of the top 
edge of the box 

minw 

int_in[2] 

= 

The box's minimum width, in pixels 

minh 

int_in[3] 

= 

The box's minimum height, in pixels 

Results 

status 

int_out[0] = 

Error status code; 

0 — an error occurred during 
execution 

>0 = no error occurred during 
execution 

endw 

int_out[l] = 

The width of the box at the time the user 
released the left mouse button 

endh 

int_out[2] = 

The height of the box at the time the user 
released the left mouse button 


See also 

form_do( ), evnt_multi( ), evnL_button( ) 
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graf— dragbox 


Let the User Drag a Box 

graf— dragbox( ) Opcode =71 

This function draws a dotted box outline on the screen, which stays a fixed 
distance from the mouse pointer so long as the user holds down the left 
mouse button. This box is dragged within a boundary rectangle defined by 
the program. When the left mouse button is released, the function ends, and 
the box is erased. This function should only be called when the program has 
determined that the left mouse button is already down, by returns from 
form— do( ), evnt— multi( ), or evnt— buttonf ), since, if it's up, the function 
will end as soon as it's called. 

C binding 

int status, width, height, beginx, beginy; 

int boundx, boundy, boundw, boundh, endx, endy; 

status = graf— dragbox(width, height, beginx, beginy, boundx, boundy, 
boundw, boundh, &endx, &endy); 


Inputs 



control] 

control] 

control! 

control! 

control! 

[0 

1 

2 

3 

4 

= 71 
= 8 
= 3 
« 0 
= 0 

L Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int— out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr— out 
array 

width 

int-in[0 

= 

The width of the box, in pixels 

height 

int-injl 

= 

The height of the box, in pixels 

beginx 

int— in[2 

= 

The horizontal position of the left edge of 
the box at the beginning of the call 

beginy 

int — ln[3] 


The vertical position of the top edge of the 
box at the beginning of the call 

boundx 

int— in[4] 


The horizontal position of the left edge of 
the boundary rectangle. The box outline 
cannot be dragged past the borders of this 
imaginary screen rectangle. 

boundy 

int— in[5] 

= 

The vertical position of the top edge of the 
boundary rectangle 

boundw 

int— in[6] 

== 

The width of the boundary rectangle, in 
pixels 

boundh 

int— in[7] 


The height of the boundary rectangle, in 
pixels 

Results 

status 

int— out[0] « 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 
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graf— dragbox 


endx 

int_out[l] = 

The screen position of the box's left edge 
at the time the user released the left 
mouse button 


endy 

int_out[2] — 

The screen position of the box's top edge 
at the time the user released the left 
mouse button 



See also 

form_do( ), evnt_multi( ), evnt_button( ) 
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grafLmbox 


Draw a Moving Box 

gra£_mbox( ) Opcode =72 

Draws and erases a series of box outlines to give the impression of a box 
moving from one position onscreen to another. 

C binding 

int status, width, height, beginx, beginy, endx, endy; 

status = graf— mbox(width, height, beginx, beginy, endx, endy); 

Note: Digital Research documentation refers to this function as 
graf— movebox( ). However, the C language bindings released by Atari Cor- 
poration with the Alcyon C compiler and libraries derived from Atari's code 
(such as those supplied with the Megamax C compiler) use the graf— mbox( ) 
terminology. Therefore, in order to link properly with current versions of the 
library, your program must also use the graf— mbox( ) form. If in the future 
Atari decides to change its libraries to conform to its documentation, you'll 
need to change over to graf— movebox( ) as well. 


Inputs 



control[0] = 72 
control[l] = 6 
control[2] = 1 
control[3] =* 0 
control[4] = 0 

Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int— out array 
Number of 3 2 -bit inputs in addr_in array 
Number of 32-bit results in addr— out 
array 

width 

int_in[0] = 

The width of the box, in pixels 

height 

int— in[l] = 

The height of the box, in pixels 

beginx 

int— in[2] = 

The screen position of the left edge of the 
first rectangle 

beginy 

int_ in[3] = 

The screen position of the top edge of the 
first rectangle 

endx 

int_ in[4] = 

The screen position of the left edge of the 
final rectangle 

endy 

int— in[5] = 

The screen position of the top edge of the 
final rectangle 

Results 

status 

int_ out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 
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Draw an Expanding Box 

graf_growbox( ) Opcode =73 

Draws and erases a series of increasingly larger boxes, to give the appear- 
ance of a box expanding from a small size to a larger size. May be used, for 
example, before opening a window with the wincL.open( ) call, to make the 
window look as if it's exploding open. 

C binding 

int status, smallx, smally, smallw, smallh; 
int largex, largey, largew, largeh; 

status = graf_growbox(smallx, smally, smallw, smallh, largex, largey, 
largew, largeh); 


Inputs 


smallx 

control[0] = 73 
controljl] = 8 
control[2] = 1 
control(3] = 0 
control[4] = 0 

int_in[0] = 

Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int-_out array 
Number of 32-bit inputs in addr_Jn array 
Number of 32-bit results in addr_out 
array 

The screen position of the left edge of the 

smally 

int_in[l] = 

starting (small) rectangle 

The screen position of the top edge of the 

smallw 

int_in[2] = 

starting (small) rectangle 

The width of the starting (small) box, in 

smallh 

int in(3] = 

pixels 

The height of the starting (small) box, in 

largex 

int_in[4] = 

pixels 

The screen position of the left edge of the 

largey 

int-in[5] = 

ending (large) rectangle 

The screen position of the top edge of the 

largew 

int_in[6] = 

ending (large) rectangle 

The width of the ending (large) box, in 

largeh 

int_in[7] = 

pixels 

The height of the ending (large) box, in 


pixels 

Results 

status 

int_out[01 = 

Error status code: 

See also 

wind_open( ), graf— shrinkbox( ) 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 
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graL_shrinkbox 


Draw a Contracting Box 

graf_ shrinkbox( ) Opcode =74 

Draws and erases a series of increasingly smaller boxes, to give the appear- 
ance of a box contracting from a large size to a smaller size. May be used, 
for example, before closing a window with wind_close( ), to make it look 
like the window is actually folding in on itself. 

C binding 

int status, smallx, smally, smallw, smallh; 
int largex, largey, largew, largeh; 

status ~ graf— shrinkbox(largex, largey, largew, largeh, smallx, smally, 
smallw, smallh); 


Inputs 


smallx 

control[0] = 74 
control[l] = 8 
control[2] = 1 
control[3] = 0 
control[4] = 0 

int_Jn[0] = 

Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

The screen position of the left edge of the 

smally 

int_Jn[l] = 

ending (small) rectangle 

The screen position of the top edge of the 

smallw 

int_in[2] = 

ending (small) rectangle 

The width of the ending (small) box, in 

smallh 

int in[3] = 

pixels 

The height of the ending (small) box, in 

largex 

int— in[4] = 

pixels 

The screen position of the left edge of the 

largey 

int in[5] = 

starting (large) rectangle 

The screen position of the top edge of the 

largew 

int_in[6] = 

starting (large) rectangle 

The width of the starting (large) box, in 

largeh 

int_in[7] = 

pixels 

The height of the starting (large) box, in 


pixels 

Results 

status 

int_out[01 = 

Error status code: 

See also 

wind_close( ), graf__growbox( ) 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 



graf_watchbox 


Watch an Object Rectangle 

graf_watchbox( ) Opcode =75 

This function follows the mouse pointer as it moves in and out of a specified 
object rectangle, so long as the user holds down the left mouse button. The 
caller may specify that the object changes state when the mouse pointer 
moves on or off of it, and the function will redraw the object each time the 
state change occurs. When the left mouse button is released, the function 
ends, and it returns a code indicating whether the mouse pointer ended up 
within the object rectangle or outside. It should only be called when the 
program has determined that the left mouse button is already down, by re- 
turns from form— do( ), evnt_multi( ), or evnt— button( ). If it's up, the func- 
tion will end as soon as it's called. This function is used internally by 
form— do( ) to handle object selection. 

C binding 

int in— or— out, object, instate, outstate; 

OBJECT ’tree; 

in— or— out = graf— watchbox(tree, object, instate, outstate); 


Inputs 


reserved 

object 

instate 

outstate 

tree 


control! 

control! 

control! 

controlj 

control 


75 

4 

1 

1 

0 


int— in[0] = 
int in[l] = 


int— in[2] = 


int— in[3] = 


addr— in[0] = 


Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int-out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr— out 
array 

Reserved for future use 

The number (array index) of the object to 

watch 

The ob— state flag setting of the object 
when the mouse pointer (with button 
down) is inside of its rectangle 
The ob-state flag setting of the object 
when the mouse pointer (with button 
down) is outside of its rectangle 
The address of the object tree array which 
contains the object 


Results 

in— or_out int— out[0] = A code indicating the relative position of 

the mouse pointer when the user released 
the left mouse button: 

0 = pointer is outside of object 
rectangle 

1 = pointer is inside of object rectangle 


See also 

form— do( ), evnt-multi( ), evnt— button( ) 
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graf— slidebox 


Let the User Drag a Box Object 

gra£_ slidebox( ) Opcode =76 

This function draws a moving box outline which is the same size as a box 
object (slider) which is contained within a parent box object (slide bar). This 
moving box follows the mouse pointer, within the constraints of its con- 
tainer, so long as the user holds down the left mouse button. When the left 
mouse button is released, the function ends, and it returns a code indicating 
the relative position of the slider object within the slide bar object. It should 
only be called when the program has determined by returns from form_do( ), 
evnt_multi( ), or evnt_button( ), that the mouse pointer is positioned over 
the object and the left mouse button is down, since if the button is up when 
the call is made, the function will end immediately. This function can be 
used, for example, to implement a slide bar in a dialog, by making the slider 
a TOUCHEXIT object. 

C binding 

int status, parent, object, orientation; 

OBJECT *tree; 

position = graf— slidebox(tree, parent, object, orientation); 


Inputs 



x£> 

IS. CO rH rH O 

(I II II II II 

O *1 CM CO 

mu 

c c c c c 
8 8 8 8 8 

Opcode 

Number of 16-bit inputs in int_ in array 
Number of 16-bit results in int_ out array 
Number of 32-bit inputs in addr_ in array 
Number of 32-bit results in addr_ out 
array 

parent 

int_in[0] = 

The number (array index) of the parent 
box object (slide bar) 

object 

int_in[l] — 

The number (array index) of the child box 
object (slider) 

orientation 

int_in[2] = 

A code indicating the orientation of the 
slide bar rectangle: 

0 = horizontal (slider moves left-right) 

1 = vertical (slider moves up-down) 

tree 

addr_in[0] = 

The address of the object tree array which 
contains the objects 

Results 

position 

int— out[0] = 

A code indicating the position of the slider 
object relative to the parent slide bar. This 
code is a number in the range 0-1000, 
where, depending on orientation: 

0 = left or top 
1000 = right or bottom 
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graf-handle 




Get the Physical Screen Handle 

gra£_handle( ) Opcode =77 

This function returns the VDI handle number for the current physical screen 
workstation, along with some information about the default system font. 

The physical screen workstation is needed in order to open a virtual screen 
workstation with the v_opnvwk( ) call. 

C binding 

int phys_ handle, cellw, cellh, boxw, boxh; 

phys_handle = graf_ handle(&cellw, &cellh, &boxw, &boxh); 


Inputs 


control[0] 

control[l] 

control[2] 

control[3] 

control[4] 


77 Opcode 

0 Number of 16-bit inputs in int_in array 
5 Number of 16-bit results in int_out array 

0 Number of 32-bit inputs in addr_in array 

0 Number of 32-bit results in addr— out 
array 


Results 

phy$— handle int_out[0] = 
cellw int— out[l] = 


cellh 

int— out[2] — 

boxw 

int_ out[3] = 


boxh int_out[4] = 


The VDI handle for the current physical 
screen workstation 

The width, in pixels, of a character cell in 
the default system font (the one used to 
render text in menus and dialogs). The 
character cell is the entire space taken up 
by each character, including the 
intercharacter spacing. 

The height, in pixels, of a character cell in 
the default system font (the one used to 
render text in menus and dialogs) 

The width, in pixels, of a box surrounding 
a character cell in the default system font. 
Several GEM objects, such as vertical 
scroll bars, the close box, and size box are 
boxw pixels wide. 

The height, in pixels, of a box surrounding 
a character cell in the default system font. 
Several GEM objects, such as horizontal 
scroll bars, the title bar, information line, 
close box, and size box are boxh pixels 
high. 





n 

n 



n 

n 
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graf— mouse 






u 

u 



Change the Mouse Pointer 

gra£_mouse( ) Opcode =78 

Changes the shape of the mouse pointer. The caller may request one of 
eight predefined mouse pointer shapes or a user-defined shape made up of a 
16 X 16-pixel bit image. This function may also be used to erase the mouse 
pointer before graphics operations are performed and to restore it after they 
are finished. This is necessary because the background behind the pointer is 
saved in a buffer and restored when the pointer is moved. If the mouse 
pointer isn't turned off during a drawing operation, the previous background 
image behind the pointer may be accidentally restored on top of the new 
background image created by the drawing operation. 

If an application chooses to change the mouse pointer shape, it should only 
do so when the pointer is within the active (topmost) window. When the 
pointer leaves the active window, the program should change its shape back 
to an arrow or bee (shape 0 or 2). The application can use evnt_ mouse( ) or 
evnt__multi( ) to track the movement of the mouse in and out of the active 
window rectangle, so as to know when to change mouse shape. 


C binding 

int status, form— no, formptr[37]; 

status = graf— mouse(form_no, formptr); 


Inputs 


form_no 


control[0] = 78 
control[l] = 1 
control[2] = 1 
control[3] = 1 
control[4] = 0 

int_ in[0] 5=1 


Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_ in array 
Number of 32-bit results in addr_out 
array 

A code indicating the new shape that the 
mouse pointer will assume. Valid code 
numbers include: 


Form 

Number 

0 

1 

2 

3 

4 

5 

6 
7 

255 

256 

257 


Shape 

Arrow 

Vertical bar (I-beam) 
Bee 

Pointing hand 
Flat hand 
Thin crosshairs 
Thick crosshairs 
Outline crosshairs 
User defined 
Mouse pointer off 

Mouse pointer on 


Macro Name 

ARROW 

TEXT— CRSR 

HOURGLASS 

POINT-HAND 

FLAT-HAND 

THIN-CROSS 

THICK-CROSS 

OUTLN— CROSS 

USER— DEF 

M-OFF 

M_ON 


Usage 

General purposes 

Text cursor placement 

Busy signal 

Sizing 

Dragging 

Drawing 

Application -sp e cif ic 

Application-specific 

Application-specific 

Hide mouse before 

drawing 

Restore 
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fonnptr addr_in[0] = The address of a 37-word array that con- 

tains the data for the custom pointer 
shape. If one of the predefined shapes 
requested, this value may be set to OL. 
custom pointer is desired, the data array 
must first be set up, and its beginning ad- 
dress placed here. The format for this ar- 
ray is 

Element 

Number Description of Contents 

0 X position of "hot spot" 

1 Y position of "hot spot" 

2 Number of bit planes (must be set to 1) 

3 Background color (normally 0) 

4 Foreground color (normally 1) 

5-20 16 words of color mask data 

21-36 16 words of image data 

Results 

status int_out[0] = Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 
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graf_mkstate 


Get Mouse and Shift-Key Status 

graf_mkstate( ) Opcode =79 

The graf— mkstate( ) call provides information about the current position of 
the mouse pointer on the screen and the current state of the mouse buttons 
and shift keys. Though this is the same kind of information returned by the 
evnt_button( ) and evnt—multi calls, the difference is that graf— mkstate( ) 
doesn't wait until an event occurs. Rather, it returns immediately, reporting 
the current status of the mouse buttons and shift keys. This makes it suitable 
for use in a polling routine that checks one or both of the mouse buttons. 

Note that AES input functions like graf_mkstate( ) should never be mixed 
with VDI functions, or GEM will get very confused. Your program should 
use AES input functions or VDI input functions, but not both. 

C binding 

int reserved, mousex, mousey, mousbutn, shiftkey; 

reserved = graf— mkstate(&mousex, &mousey, &mousbutn, &shiftkey); 


Inputs 



control[0] = 79 
control[l] = 0 
control[2] = 5 
control 3] » 0 
control[4] « 0 

Results 

reserved 

mousex 

int— out[0] = 
int— out[l] = 

mousey 

int— out[2] = 

button 

int— out[3] = 

shiftkey 

int— out[4] = 


Bit Bit Value Key 

0 1 Right Shift 

1 2 Left Shift 

2 4 Control 

3 8 Alt 


Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 


Reserved for future use; always equals 1 
The horizontal position of the mouse 
pointer at the end of the function 
The vertical position of the mouse pointer 
at the end of the function 
The final mouse button state: 

0 = both buttons up 

1 = left button down, right button up 

2 = right button down, left button up 

3 5=5 both buttons down 

The status of the keyboard shift keys. 

Each key is represented by a different bit. 
A 1 in that bit position means that the key 
is down, while a 0 means that it's up: 


See also 

evnt— button( ), evnt— multi( ) 
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scrp— read 




Read Scrap Directory 

scrp_read( ) Opcode =80 

By GEM convention, a disk may be used for a clipboard function to save 
data the user selects for a CUT or COPY operation. The program writes this 
data to disk in a file called SCRAP. This file may have any of several file- 
name extensions (.TXT, .DIF, .IMG, and so on), depending on the type of 
data it contains, such as text, graphics, or spreadsheet data. So that other 
programs may share this data, when the program writes the file to disk, it 
gives the AES the pathname of the directory where the file resides, by using 
the scrp_ write( ) function. When another program wishes to use that data, it 
finds the directory by using scrp— read( ). 


C binding 

int status; 
char path[128]; 

status = scrp— read(path); 


Inputs 


Results 

status 


control| 

control| 

control) 

controlj 

control! 



addr_ in[0) = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int—out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr_ out 
array 

The address of the buffer into which the 
scrap directory path will be written 


inLout[0] = Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

scrp_write( ) 



n 
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scrp_write 


Write Scrap Directory 

scrp_write( ) Opcode =81 

By GEM convention, a disk may be used for a clipboard function to save 
data the user selects for a CUT or COPY operation. The program writes this 
data to disk in a file called SCRAP. This file may have any of several file- 
name extensions (.TXT, .DIF, .IMG, and so on), depending on the type of 
data it contains, such as text, graphics, or spreadsheet data. So that other 
programs may share this data, when the program writes the File to disk, it 
gives the AES the pathname of the directory where the file resides, by using 
the scrp_write( ) function. When another program wishes to use that data, it 
finds the directory by using scrp_read( ). 

C binding 

int status; 
char path[128]; 

status = scrp_write(path); 


Inputs 



control[0] = 81 
control[l] = 0 
control[2] = 1 
control[3] = 1 
control[4] = 0 

Opcode 

Number of 16-bit inputs in inLJn array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 

path 

addr_in[0] = 

array 

Address of the buffer containing the text 
string which specifies the new scrap direc- 
tory path 

Results 

status 

int_out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

scrp_read( ) 
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fseL_ input 


Display File Selector 

fsel_ input( ) Opcode =90 

The File Selector is prepared dialog which displays a disk directory and ob- 
tains a pathname and filename from the user. The fsel_Jnput( ) function dis- 
plays this dialog, monitors the user's interaction with it, and returns the path 
and file names. Note that the directory display is limited to 100 files in any 
directory. After the user exits the file selector, the AES sends a redraw mes- 
sage to the application to repair the section of the window that was located 
under the selector dialog box. Your program should be prepared to handle 
that message by repairing the damage fsel_input( ) does to the display. Also 
you should note that fsel_input( ) changes the current VDI clipping rectan- 
gle and doesn't change it back upon exit from the routine. Therefore, if your 
program does any VDI rendering after a call to fseL_input( ), you'll probably 
have to set the clipping rectangle afterward, whether you normally use clip- 
ping or not. 

C binding 

int status, exitbutn; 
char path[64], file[13]; 

status = fsel_input(path, file, &exitbutn); 

Inputs 

control(0] = 90 
controlfl] = 0 
control[2] = 2 
control[3] = 2 
control[4] = 0 

path addr_in[0] = 


file addr_ in[l] = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_Jn array 
Number of 32-bit results in addr_out 
array 

The address of the buffer that holds the 
text string which specifies the path for the 
directory that's initially displayed in the 
dialog. This path name should use 
wildcards in the filename position (for in- 
stance, A: \ UTILITIES \ V or 
C: \ GAMES \*.PRG). The call returns the 
user's final pathname selection in this 
same buffer. 

The address of the buffer that holds the 
text string which specifies the initial file 
selection that's displayed in the dialog 
box. The call returns the user's final file- 
name selection in this same buffer. 
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fseLJnput 


int_out[0] = Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 

int-out[l] = A code which specifies the exit button 

which the user selected in order to end the 
dialog: 

0 = Cancel 

1 = OK 


u 

u 

u 

u 

u 
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wind— create 


Allocate a Window 

wind_create( ) Opcode =100 

This function allocates the necessary resources for a window of a given max- 
imum size having certain specified attributes. It returns a window handle 
that is used to identify the window. This function does not actually display 
the window on the screen, however. The wind— open( ) function is used for 
that purpose. Before the appl— exit( ) call is made to indicate that the applica- 
tion is about to terminate, all of the window resources should be released by 
using the wind_delete( ) call. 


C binding 

int wi—handle, controls, fullx, fully, fullw, fullh; 

wi_handle = wind— create(controls, fullx, fully, fullw, fullh); 


Inputs 


controls 


control^ 

control[l 

control[2: 

control[3 

control[4 


int_in[0] — 


100 Opcode 

5 Number of 16-bit inputs in int— in array 
1 Number of 16-bit results in int_out array 

0 Number of 32-bit inputs in addr— in array 

0 Number of 32-bit results in addr_out 
array 

A code which specifies the window con- 
trol components which will be present in 
this window. Each window control is rep- 
resented by a bit in this word. If the bit 
which corresponds to a given control is set 
to 1, that control is present. The bit as- 
signments are 


Bit 

Bit Value 

Macro Name Window Control 

0 

1 (0x001) 

NAME 

Title bar 

1 

2 (0x002) 

CLOSER 

Close box 

2 

4 (0x004) 

FULLER 

Full box 

3 

8 (0x008) 

MOVER 

Move bar 

4 

16 (0x010) 

INFO 

Information line 

5 

32 (0x020) 

SIZER 

Size box 

6 

64 (0x040) 

UPARROW 

Up arrow for vertical scroll bar 

7 

128 (0x080) 

DNARROW Down arrow for vertical scroll bar 

8 

256 (0x100) 

VSLIDE 

Slider for vertical scroll bar 

9 

512 (0x200) 

LFARROW 

Left arrow for horizontal scroll bar 

10 

1024 (0x400) 

RTARROW 

Right arrow for horizontal scroll bar 

11 

2048 (0x800) 

HSLIDE 

Slider for horizontal scroll bar 

fullx 

int_in[l] = 

The screen position of the left edge of the 




maximum-size window 

fully 

int_in[2] ~ 

The screen position of the top edge of the 




maximum-size window 

fullw 

int_in[3] = 

The maximum width of the window, in 




pixels 

fullh 

int_in[4] = 

The maximum height of the window, in 
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pixels 



u 

u 


wind—create 


U 

u 

u 


Results 

wLJiandle int_out[0] = A unique number in the range 0-8 used to 

identify the window. Window handle 
number 0 is reserved for the Desktop win- 
dow that's managed by the AES. If eight 
windows are already open (the maximum 
under the current version of GEM on the 
ST), a negative value will be returned, in- 
dicating that no windows were available, 
and the function failed to allocate a new 
window. 

See also 

wind_delete( ), wind— open 


u 

u 

u 

u 

u 
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wind-open 


G 

n 


Display a Window 

wind— open( ) Opcode =101 

Displays a window in its initial size and position. 

C binding 

int status, wi— handle, x, y, width, height; 

status = wind— open(wi— handle, x, y, width, height); 


Inputs 



control[0 

= 101 


controlfl 

= 5 


control[2 

= 1 


control[3 

- 0 


control[4 

= 0 

wi— handle 

int— in[0] 

= 

X 

int— in[l] 

= 

y 

int— in[2] 

= 

width 

int_in(3] 

= 

height 

int-in[4] 

= 

Results 



status 

int— out[0] = 


Opcode 

Number of 16-bit inputs in intJn array 
Number of 16-bit results in int— out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr-jout 
array 

The ID number of the window to be 
opened (returned initially by 
wind— create( ) 

The initial screen position of the window's 
left edge 

The initial screen position of the window's 
top edge 

The initial width of the window, in pixels 
The initial height of the window, in pixels 


Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

wind— close( ), wind— create( ) 


n 

n 



n 

n 

n 


□ 
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wind-close 


Erase a Window 

wind_close( ) Opcode =102 

This call removes a window from the screen. Though the window is no 
longer displayed, its resources remain allocated, and it may be reopened at 
any time until the wind_delete( ) function is used to release those resources. 

C binding 

int wL_handle, status; 

status = wind— close(wi_ handle); 


Inputs 



control[0] = 102 
controlfl] = 1 
control[2] = 1 
control[3] *= 0 
control[4] = 0 

Opcode 

Number of 16-bit inputs in int— in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_ in array 
Number of 32-bit results in addr_ out 
array 

wi_ handle 

int— in[0] = 

The ID number of the window to be 
closed 

Results 

status 

int_ out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

wind— open( ), wind— delete( ) 
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Deallocate a Window 

wind_delete( ) Opcode =103 

This call is used to release the system resources held by a window. The 
wind_close( ) call should first be used to erase the window's screen display. 
Once a window's resources have been released, it cannot be opened again 
until the wind_create( ) call is used to allocate them again. 

C binding 

int wLJiandle, status; 

status = wind_delete(wi_handle); 

Inputs 

control[0] = 103 Opcode 

control[l] « 1 Number of 16-bit inputs in int_in array 

control[2 = 1 Number of 16-bit results in int_out array 

control[3 = 0 Number of 32-bit inputs in addr_Jn array 

control[4 = 0 Number of 32-bit results in addr_out 

array 

wi_handle int_Jn[0] = The ID number of the window to be 

deleted 

Results 

status int_out[0] = Error status code: 

0 *= an error occurred during 
execution 

>0 = no error occurred during 
execution 

See also 

wind_create( ), wind_close( ) 


n 

n 

n 


□ 

n 

n 

n 
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wind— get 


Get Window Information 

wind— get( ) Opcode =104 

This function can be used to learn about the size and position of the win- 
dow rectangle and its scroll bars. 

C binding 

int status, wLJiandle, flag, x, y, width, height; 

status = wind— get(wi— handle, flag, &x, &y, &width, &height); 


Inputs 

control[0] = 
control|l] = 
control[2] = 
control[3] = 
control[4] = 

wi— handle int_in[0] = 

flag intJn[l] = 

Flag Macro Name I 

4 WF— WORKXYWH V 

5 WF— CURRXYWH V 

6 WF-JPREVXYWH I 

7 WF— FULLXYWH ^ 

8 WF— HSLIDE * 

1 . 

9 WF_ VSLIDE y 

I 

10 WF-TOP x 

11 WF— FIRSTXYWH C 

c 

12 WF— NEXTXYWH C 


1 J 13 

WF— RESVD 

W 15 

WF— HSLSIZE 

u 

16 

i i 

WF— VSLSIZE 

u 17 

WF-SCREEN 

U 



- 104 Opcode 

= 2 Number of 16-bit inputs in int— in array 

= 5 Number of 16-bit results in int— out array 

= 0 Number of 32-bit inputs in addr— in array 

= 0 Number of 32-bit results in addr— out 

array 

The ID number of the window about 
which information is to be provided 
A code indicating the type of information 
requested. Valid numbers include: 

Information Requested 

Window work area coordinates 
Window exterior coordinates 
Previous window exterior coordinates 
Maximum window exterior coordinates 
x — relative position of horizontal slider (1 = 
leftmost position, 1000 = rightmost) 
y = relative position of vertical slider (1 = top 
position, 1000 = bottom) 
x = window handle of the top (active) window 
Coordinates of the first rectangle in the win- 
dow's rectangle list 

Coordinates of the next rectangle in the win- 
dow's rectangle list 
Reserved for future use 
x = relative size of the horizontal slider com- 
pared to the scroll bar (— 1 = minimum size, 
1-1000 = percentage filled, in tenths of a 
percent) 

y = relative size of the vertical slider compared 
to the scroll bar (—1 = minimum size, 1-1000 
= percentage filled, in tenths of a percent) 
Address and length of the menu /alert buffers (x 
= low word of address, y — high word, width 
= low word of length, height = high word) 


u 
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wind— get 




Results 

Except where noted above in the description of the flag variable (int_in[l]), 
the four values returned specify the horizontal position, vertical position, 
width, and height of a screen rectangle. For functions 8, 9, 10, 15, and 16, 
the value in int_out[l] — associated with the variable name x — has some sig- 
nificance other than being a horizontal screen position value. For function 
number 17, the value in int_out[2] is used as the second part of an address. 
For specifics, see the descriptions of the various subfunctions. 

status int_out[0] = Error status code: 

0 = an error occurred during 


X 

int_out[l] = 

execution 

>0 = no error occurred during 
execution 

The screen position of the left side of the 

y 

int_out[2] = 

window rectangle 

The screen position of the top edge of the 

width 

int_out[3] = 

window rectangle 

The width of the window rectangle, in 

height 

int_out[4] = 

pixels 

The height of the window rectangle, in 

See also 
wind— set( ) 


pixels 





□ 

□ 

G 

n 

n 
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wind-set 


Change Window Settings 

wind— set( ) Opcode =105 

This function can be used to change a number of settings which affect the 
way in which a window is displayed. 


C binding 

int status, wi— handle, field, x, y, width, height; 

status = wind— set(wi— handle, field, x, y, width, height); 


Inputs 


wi— handle 
field 


control] 

controlj 

control! 

control! 

control 


int_in[0] 


int— in[l] = 


105 Opcode 

6 Number of 16-bit inputs in int-in array 
1 Number of 16-bit results in int— out array 

0 Number of 32-bit inputs in addr— in array 

0 Number of 32-bit results in addr— out 
array 

The ID number of the window whose 
settings are to be changed 
A code which specifies the window setting 
to change. Valid setting changes are 


Field 


Number 

Macro Name 

Aspect to Change 

1 

WF—KIND 

x = Window controls flag (same as controls 
for wind— create( ) ) 

2 

WF-NAME 

x,y = Address of string containing the 
name of the window 

3 

WF-INFO 

x,y = Address of string for the window's 
information line 

5 

WF—CURRXYWH 

Window exterior coordinates 

8 

WF-HSLIDE 

x = relative position of horizontal slider (1 
= leftmost position, 1000 *=* rightmost) 

9 

WF—VSLIDE 

x = relative position of vertical slider (1 = 
top position, 1000 = bottom) 

10 

WF-TOP 

x = window handle of the top (active) 
window 

14 

WF-NEWDESK 

The address of an object tree to be used for 
the Desktop Window background (x = low 
word, y = high word of address, width — 
number of starting object to draw) 

15 

WF—HSLSIZE 

x = relative size of the horizontal slider 
compared to the scroll bar (—1 = minimum 
size, 1-1000 = percentage filled, in tenths 
of a percent) 

16 

WF—VSLSIZE 

x = relative size of the vertical slider com- 


pared to the scroll bar ( — 1 = minimum 
size, 1-1000 = percentage filled, in tenths 
of a percent) 
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X 

int_in[2] = 

Specific to setting; as described above 

y 

int_in[3] = 

Specific to setting; as described above 

width 

int_in[4] = 

Specific to setting; as described above 

height 

int_in[5] = 

Specific to setting; as described above 

Results 

status 

int_out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

wind_get( ) 




292 


n 

n 

n 




u 

u 




wind— find 


Find Window Under Mouse Pointer 

wind__find( ) Opcode =106 

This function determines which window is currently under the mouse 
pointer, either the Desktop window (handle 0) or one of the application 
windows, whose handles are assigned by the wincLcreate( ) call. 


C binding 

int wi_handle, mousex, mousey; 

wi_handle = wind_find(mousex, mousey); 


Inputs 



control[0 

= 106 


controlfl 

= 2 


control[2 

= 1 


control[3 

= 0 


control[4 

= 0 

mousex 

int_in[0] 

= 

mousey 

int-in[lj 

= 

Results 



wi—handle 

int_out[0] = 

See also 



objc_ find( ) 




Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

The horizontal screen position of the 
mouse pointer 

The vertical screen position of the mouse 
pointer 


The ID number of the window located at 
the specified position 





u 
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wind— update 


□ 

□ 


Lock or Release Screen for Update 

wind— update( ) Opcode =107 

This function is normally used to notify the AES prior to a screen update, so 
the AES won't change the screen display in that area (by dropping down a 
menu, for example). It can also be used by an application to take complete 
control of all mouse functions, even when the mouse is located outside of 
the active application window (in the menu bar, for example). 


C binding 

int status, code; 

status = wind— update(code); 


Inputs 


code 


control[0] = 107 
control[l] = 1 
control[2] = 1 
control[3] = 0 
control[4] = 0 

int_Jn[0] = 


Opcode 

Number of 16-bit inputs in inLJn array 
Number of 16-bit results in int— out array 
Number of 32-bit inputs in addr— in array 
Number of 32-bit results in addr_out 
array 

A code which specifies the function this 
call will perform. Valid code numbers are 


Code Macro Name 

0 BEG-UPDATE 

1 END— UPDATE 

2 BEG— MCTRL 

3 END— MCTRL 


Function 

Notifies AES that the application is beginning a 
window display update 

Notifies AES that the application is ending its win- 
dow display update 

Notifies AES that the application is taking control 
of all mouse functions, even when it moves out of 
the active window 

Notifies AES that it should once more take control 
of the mouse when it leaves the active window 
area 


Results 

status int— out[0] = Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 







n 
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wind— calc 


Calculate Window Area 

wind_calc( ) Opcode =108 

Given the size and position of either the window's border rectangle or work 
rectangle, and its window control components, this function calculates the 
size and position of the opposite rectangle. 


C binding 

int status, type, controls, knownx, knowny, knownw, knownh, otherx, 
othery, otherw, otherh; 

status = wind—calc (type, controls, knownx, knowny, knownw, knownh, 
&otherx, fcothery, fcotherw, fcotherh); 


Inputs 


type 


controls 


control| 

control) 

controlj 

control] 

control 


int_in[0] 


int_in[l] — 


108 Opcode 

6 Number of 16-bit inputs in int_Jn array 
5 Number of 16-bit results in int_out array 

0 Number of 32-bit inputs in addr_ in array 

0 Number of 32-bit results in addr_ out 
array 

A code specifying the type of calculation 
to perform: 

0 = return border position and size 

1 = return work position and size 

A code which specifies the window con- 
trol components present in this window. 
Each window control is represented by a 
bit in this word. If the bit which corre- 
sponds to a given control is set to 1, that 
control is present. The bit assignments are 


Bit 

Bit Value 

Macro Name 

0 

1 (0x001) 

NAME 

1 

2 (0x002) 

CLOSER 

2 

4 (0x004) 

FULLER 

3 

8 (0x008) 

MOVER 

4 

16 (0x010) 

INFO 

5 

32 (0x020) 

SIZER 

6 

64 (0x040) 

UPARROW 

7 

128 (0x080) 

DNARROW 

8 

256 (0x100) 

VSLIDE 

9 

512 (0x200) 

LFARROW 

10 

1024 (0x400) 

RTARROW 

11 

2048 (0x800) 

HSLIDE 


Window Control 
Title Bar 
Close Box 
Full Box 
Move Bar 
Information Line 
Size Box 

Up arrow for vertical scroll bar 
Down arrow for vertical scroll bar 
Slider for vertical scroll bar 
Left arrow for horizontal scroll bar 
Right arrow for horizontal scroll bar 
Slider for horizontal scroll bar 


knownx int_Jn[2] = 

knowny int_in[3] = 

knownw int_in[4] = 


The screen position of the left edge of the 
known rectangle 

The screen position of the top edge of the 
known rectangle 

The width of the known rectangle, in 
pixels 
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wind—calc 


□ 

n 


knownh 

int_in[5] = 

The height of the known rectangle, in 
pixels 

Results 

status 

int_out[0] = 

Error status code: 

0 — an error occurred during 
execution 

>0 = no error occurred during 
execution 

otherx 

int— out[l] = 

The screen position of the left edge of the 
unknown rectangle 

othery 

int_out[2] = 

The screen position of the top edge of the 
unknown rectangle 

otherw 

int_out[3] — 

The width of the unknown rectangle, in 
pixels 

otherh 

int_out[4] = 

The height of the unknown rectangle 


□ 

n 

□ 


n 

n 

n 

n 
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rsrc— load 


U 

U 

u 



Load a Resource 

rsrc_ load( ) Opcode =110 

This function allocates memory for a resource file, loads it into memory, and 
performs the steps required to change the file into an object array of the 
proper format. TTiese steps include changing array offsets into absolute ad- 
dresses, and character-aligned screen references into absolute horizontal and 
vertical positions. The rsrc_load( ) function calls the routines rsrc— obfix( ) 
and rsrc_saddr( ) to perform these conversions. Once the resource has been 
loaded into memory, the address of a particular array element may be found 
using the rsrc_ gaddr( ) function. 

C binding 

int status; 
char '•‘filename; 

status 53 rsrc— load(filename); 


Inputs 



control| 

[0] = 110 

Opcode 


controlj 

1] = 0 

Number of 16-bit inputs in int— in array 


controlj 

2] = 1 

Number of 16-bit results in int— out array 


controlj 

3] = 1 

Number of 32-bit inputs in addr— in array 


controlj 

4] = 0 

Number of 32-bit results in addr— out 
array 

filename 

addr— in[0] = 

The address of a null-terminated text 
string which contains the path and file- 
name of the resource file to load 

Results 

status 

int— out[0] = 

Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

rsrc— gaddr( ), rsrc_saddr( ), rsrc— obfix( ) 


u 

u 

u 

u 
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Unload a Resource File 

rsrc_free( ) Opcode =111 

This function frees the memory space allocated for the resource file by the 
rsrc_load( ) call. It should be used by an application before loading a re- 
placement resource file, and before calling appLexit( ) to notify the AES 
that the application is about to terminate. 

C binding 

int status; 

status = rsrc_ free( ); 

Inputs 

control[0] = 111 Opcode 

control[lj = 0 Number of 16-bit inputs in int—in array 

control[2 = 1 Number of 16-bit results in int_out array 

control 3=0 Number of 32-bit inputs in addr_in array 

control[4] = 0 Number of 32-bit results in addr_out 

array 

Results 

status int_out[0] = Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 

See also 

rsrc_load( ) 


n 

n 

n 


□ 

n 

n 

n 

n 
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rsrc— gaddr 


Get Address of Resource Data 

rsrc_ gaddr( ) Opcode =112 

This function is used to find the address of a data structure within a re- 
source file that was loaded with rsrc_load( ). 


C binding 

int status, type, index; 
long address; 

status = rsrc_gaddr(type, index, fcaddress); 


Inputs 


type 


control] 

[0] 

= i: 

control] 

1 

= 2 

control] 

2 

= 1 

control 

3 

= 0 

control 

4 

= 1 

int_in[0] 

= 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

A code specifying the type of structure 
containing the data whose address is to be 
returned. Valid code numbers are 


Type 

Number 

0 

1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 


index 


Macro Name 

Structure 

R-TREE 

Object tree 

R_OBJECT 

OBJECT 

R—TEDINFO 

TEDINFO 

R—ICONBLK 

ICONBLK 

R_BITBLK 

BITBLK 

R__STRING 

Pointer to free strings 

R—IMAGEDATA 

Pointer to free image data 

R_OBSPEC 

Ob_spec field of OBJECT 

R_TEPTEXT 

Te-ptext field of TEDINFO 

R_TEPTMPLT 

Te—ptmplt field of TEDINFO 

R_TEPVALID 

Te_pvalid field of TEDINFO 

R__IBPMASK 

Ib_pmask field of ICONBLK 

R_IBPDATA 

Ib_pdata field of ICONBLK 

R-JBPTEXT 

Ib_ptext field of ICONBLK 

R_BIPDATA 

Bi_pdata field of BITBLK 

R__FRSTR 

Adlfrstr — the address of a pointer to a free 
string 

R—FRIMG 

Ad—frimg — the address of a pointer to a free 
image 

int_in[l] = 

The array index within the structure of the 
data whose address is sought 
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rsrc_gaddr 


n 

n 


Results 

status int_out[0] = Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 

address addr_out[0] = The address of the data whose position is 

specified by index and whose type is spec- 
ified by the type variable. 

See also 

rsrc_load( ) 


□ 

n 

n 


n 

n 

n 

n 
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rsrc— saddr 


Store Address of Resource Data 

rsrc_ saddr( ) Opcode =113 

This function is used to store the address of a data structure within one of 
the elements of the arrays that was contained in the resource file that was 
loaded. It's used by rsrc_load( ) to fix the addresses of pointer fields like 
ob—spec, te_ptext, etc. It can also be used by an application, for example, to 
dynamically change the text field of a string object. 

C binding 

int status, type, index; 
long address; 

status = rsrc_ saddr(type, index, address); 


Inputs 


type 


control| 

control] 

control! 

control| 

control 


= 113 
= 2 
= 1 
= 1 
= 0 


int in[0] = 


Opcode 

Number of 16-bit inputs in inL_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_Jn array 
Number of 32-bit results in addr_out 
array 

A code specifying the type of structure 
into which the address will be placed. 
Valid code numbers are 


Type 

Number 

0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 


index 

address 


Macro Name 

Data Structure 

R_TREE 

Object tree 

R_OBJECT 

OBJECT 

R_TEDINFO 

TEDINFO 

R-JCONBLK 

ICONBLK 

R_BITBLK 

BITBLK 

R-STRING 

Pointer to free strings 

R— IMAGEDATA 

Pointer to free image data 

R_OBSPEC 

Ob—spec field of OBJECT 

R_TEPTEXT 

Te_ ptext field of TEDINFO 

R_TEPTMPLT 

Te_ptmplt field of TEDINFO 

R— TEPVALID 

Te_pvalid field of TEDINFO 

R.JBPMASK 

Ib_pmask field of ICONBLK 

R_JBPDATA 

Ib__pdata field of ICONBLK 

R_IBPTEXT 

Ib_ptext field of ICONBLK 

R_BIPDATA 

Bi_pdata field of BITBLK 

R—FRSTR 

Adlfrstr — the address of a pointer to a free 
string 

R_FRIMG 

AcLirimg — the address of a pointer to a free 
image 

int_in[l] = 

The array index within the structure 
where the address will be placed 

addr_in[0] = 

The actual address that will be placed 
within the data structure 
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rsrc— saddr 




Results 

status 

int_out[0] = 

Error status code: 

n 



0 = an error occurred during 
execution 

>0 = no error occurred during 

n 



execution 


See also 



n 


rsrc_load( ), rsrc_gaddr( ) 



n 

n 

n 

n 
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rsrc_obfix 


Fix Object Location and Size 

rsrc_obfix( ) Opcode =114 

This function is used to change an object's location and size fields from the 
character-based coordinate system used in resource files to absolute pixels 
coordinates. It is called internally by rsrc_load( ). 

C binding 

int status, object; 
struct object tree[ ]; 

status = rsrc—obfix(tree, object); 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int— out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_ out 
array 

The number (array index) of the objects 
whose coordinates are to be converted 
The address of the object tree array which 
contains the object 


Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


rsrc_load( ) 


Inputs 

control[0] = 
control[lj = 
control[2] = 
control[3] = 
control[4] = 

object 

inL_in[0] = 

tree 

addr_in[0] — 

Results 


status 

int_out[0] = 

See also 
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she! i read 


Find Invoking Program 

shel— read() Opcode=120 

This function may be used by a GEM application to discover how it was in- 
voked, either from the GEM Desktop or from another application, and to 
read the command tail used when invoking the program. This allows the 
program to return control to the program which called it. The shel_read( ) 
function should be called after appl_Jnit( ), but before rsrc_Joad( ). 


C binding 

int status; 

char command[128], tail[128]; 

status = shel_read(command, tail); 


Inputs 


command 


tail 


Results 

status 


See also 

shel_write( ) 


control[0] =120 
control[l] = 0 
control[2] = 1 
control[3] = 2 
control[4] =* 0 

addr_in[0] = 


addr_in[l] = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_out 
array 

The address of the buffer that will hold 
the command text string. This is the drive 
specification, directory, and Filename of 
the application that invoked the current 
program. If the current program was 
loaded from the DESKTOP program, only 
a carriage-return character will be returned 
in this buffer. 

The address of the buffer that will hold 
the command tail text string. This is the 
text that followed the name of this pro- 
gram in the command string used to start 
the program. 


int_out[0] = Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 
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shel—write 







U 

U 

u 

u 


Run Another Application 

shel_write( ) Opcode =121 

This function is used to select an application other than the GEM DESKTOP 
program to load and run after the program terminates. In other words, you 
may use this command to chain programs, so that when one terminates, the 
other begins directly, without first returning to the DESKTOP. Typically, this 
function is used in conjunction with OUTPUT.PRG, the program which 
sends graphics output to the printer. Since OUTPUT.PRG relies on the 
GDOS, which has not been officially released as of this writing, it's difficult 
to say how this function will be used on the ST version of GEM. Moreover, 
this function does not work reliably in the current (preblitter) version of the 
operating system ROMs. Some of the features of this command, such as the 
“exit GEM to DOS" feature, are obviously geared to the MS-DOS version of 
GEM and are not applicable to the ST version. 


C binding 

int status, exitgem, graphics, isgem; 
char command[128], tail[128]; 


status = 

Inputs 

shel_write(exitgem, graphics, isgem, command, tail); 
control[0] = 121 Opcode 

control[l] = 3 Number of 16-bit inputs in int_in array 

control[2] = 1 Number of 16-bit results in int— out array 

control[3] = 2 Number of 32-bit inputs in addr_in array 

control[4] = 0 Number of 32-bit results in addr— out 

array 

exitgem 

int_in[0] = 

A code which indicates whether or not to 
exit GEM and return to the DOS prompt. 
Obviously inapplicable to the ST, where 
GEM is always present. 

0 = exit GEM AES 

1 = run another application 

graphics 

int_in[2] = 

A code which indicates whether the next 
application to run is a graphics applica- 
tion. Inapplicable to the ST, which always 
uses a bitmapped display. 

0 = not a graphics application 

1 = a graphics application 

isgem 

int_in[3] = 

A code which specifies whether or not the 
application to run is a GEM application 

0 = not a GEM application 

1 = a GEM application 

command 

addr_in[0] = 

The address of the buffer that holds the 
command text string. This is the drive 
specification, directory, and filename of 
the application to invoke. 

tail 

addr— in[l] = 

The address of the buffer that holds the 
command tail text string. This is the text 
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shel—write 


that follows the name of this program in 
the command string used to start the 
program. 


Results 

status int_out[0] = Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


See also 

shel-read( ) 
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Search for Filename 

sheL_find( ) Opcode =124 

This function is used to search for a Filename. It first searches the current di- 
rectory and then each directory in the current search path. If it finds the file, 

it returns its full pathname. 

C binding 

int status; 

char pathname[128]; 

status = shel_get(pathname); 

Inputs 

control[0] = 124 Opcode 

controlflj = 0 Number of 16-bit inputs in int_in array 

control[2] = 1 Number of 16-bit results in int_out array 

control[3] — 1 Number of 32-bit inputs in addr_in array 

control[4] — 0 Number of 32-bit results in addr_out 

array 

pathname addr_Jn[0] = The address of a buffer which initially 

holds the text string of the name of the 
File to search for. Upon return from this 
function, this buffer will hold the entire 
pathname of the File (including drive 
specification and directories) if the func- 
tion was able to find the file. 

Results 

status int_out[0] = Error status code: 

0 = an error occurred during 
execution 

>0 = no error occurred during 
execution 


u 

u 

u 

u 

u 
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she! envim 


□ 

n 


Search for Environment String 

shel_envrn( ) Opcode =125 

This function searches the DOS environment for an environment string and 
returns the address of the byte following that string. This is another function 
which is more applicable to the MS-DOS version of GEM than the ST 
version. 


C binding 

int reserved; 
char *textptr; 
char estring[80]; 

reserved = shel_envm(&textptr, estring); 


Inputs 


txtptr 


estring 


control[0] = 125 
control[l] = 0 
control[2] = 1 
control[3] = 2 
control[4] = 0 

addr_in[0] = 


addr_in[l] = 


Opcode 

Number of 16-bit inputs in int_in array 
Number of 16-bit results in int_out array 
Number of 32-bit inputs in addr_in array 
Number of 32-bit results in addr_ out 
array 

The function returns a pointer here to the 
address in the environment that starts 
with the character following the requested 
string. If the requested string is not found, 
a value of 0 is returned. 

The address of the buffer which holds the 
text of the environment string to search 
for (for instance, PATH=) 


Results 

reserved int_out[0] — Reserved for future use; always equals 1 



n 

n 
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Appendix B 

Extended Keyboard 
Codes 





The AES keyboard event functions (evnt_keybd and 

evnt_multi), return a two-byte value for every key pressed, 
rather than a simple one-byte ASCII code. The first byte of 
this keycode is generally a unique key identifier that refers to 
the physical key struck, regardless of shift-key combinations. 
The second byte is usually the ASCII value of the key com- 
bination, which does depend on the state of the shift keys 
(Shift, Control, and Alt). The following table shows the 
keycodes, as four-digit hexadecimal numbers, for all key and 
shift combinations. 


Main Keyboard 


Unshifted 


Shift 

CTRL 

ALT 

a 

1E61 

A 

1E41 

1E01 

1E00 

b 

3062 

B 

3042 

3002 

3000 

c 

2E63 

C 

2E43 

2E03 

2E00 

d 

2064 

D 

2044 

2004 

2000 

e 

1265 

E 

1245 

1205 

1200 

f 

2166 

F 

2146 

2106 

2100 

g 

2267 

G 

2247 

2207 

2200 

h 

2368 

H 

2348 

2308 

2300 

i 

1769 

I 

1749 

1709 

1700 

j 

246A 

J 

244A 

240A 

2400 

k 

256B 

K 

254B 

250B 

2500 

1 

266C 

L 

264C 

260C 

2600 

m 

326D 

M 

324D 

320D 

3200 

n 

316E 

N 

314E 

310E 

3100 

o 

186F 

0 

184F 

180F 

1800 

P 

1970 

P 

1950 

1910 

1900 

q 

1071 

Q 

1051 

1011 

1000 

r 

1372 

R 

1352 

1312 

1300 

s 

1F73 

S 

1F53 

1F13 

1F00 

t 

1474 

T 

1454 

1414 

1400 

u 

1675 

U 

1655 

1615 

1600 

V 

2F76 

V 

2F56 

2F16 

2F00 

w 

1177 

w 

1157 

1117 

1100 

X 

2D78 

X 

2D58 

2D18 

2D00 

y 

1579 

Y 

1559 

1519 

1500 

z 

2C7A 

Z 

2C5A 

2C1A 

2C00 
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1 J 

Unshifted 


Shift 


CTRL 

ALT n 

1 

0231 

! 

0221 

0211 

7800 ' .. i 

2 

0332 

@ 

0340 

0300 

7900 

3 

0433 

# 

0423 

0413 

7A00 l — ) 

4 

0534 

$ 

0524 

0514 

7B00 I 1 

5 

0635 

% 

0625 

0615 

7C00 

6 

0736 

A 

075E 

071E 

7D00 

7 

0837 

& 

0826 

0817 

7E00 

8 

0938 

* 

092A 

0918 

7F00 

9 

0A39 

( 

0A28 

0A19 

8000 

0 

0B30 

) 

0B29 

0B10 

8100 

— 

0C2D 


0C5F 

0C1F 

8200 

= 

0D3D 

+ 

0D2B 

0D1D 

8300 

' 

2960 


297E 

2900 

2960 

\ 

2B5C 

1 

2B7C 

2B1C 

2B5C 

[ 

1A5B 

{ 

1A7B 

1A1B 

1A5B 

] 

1B5D 

> 

1B7D 

IBID 

1B5D 

/ 

273B 


273A 

271B 

273B 

/ 

2827 

ft 

2822 

2807 

2827 

/ 

332C 

< 

333C 

330C 

332C 


342E 

> 

343E 

340E 

342E 

/ 

352F 

7 

353F 

350F 

352F 

Space 

3920 


3920 

3900 

3920 

Esc 

011B 


011B 

011B 

011B 

Backspace 

0E08 


0E08 

0E08 

0E08 

Delete 

537F 


537F 

531F 

537F 

Return 

1C0D 


1C0D 

ICO A 

1C0D 

Tab 

0F09 


0F09 

0F09 

0F09 

Cursor Pad 





Unshifted 


Shift 

CTRL 

ALT 

1 — 1 

Help 

6200 

6200 

6200 

(screen print) t 1 

Undo 

6100 

6100 

6100 

6100 


Insert 

5200 

5230 

5200 

(left mouse button) , — . 

Clr/Home 

4700 

4737 

7700 

(right mouse button) | ) 

Up- Arrow 

4800 

4838 

4800 

(move mouse up) 

Dn-Arrow 

5000 

5032 

5000 

(move mouse down) 

Rt-Arrow 

4B00 

4B34 

7300 

(move mouse right) | | 

Lft-Arrow 

4D00 

4D36 

7400 

(move mouse left) ’ 






n 
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Extended Keyboard Codes 


LJ 

1 | Numeric Pad 




Unshifted 

Shift 

CTRL ALT 


i i ( 

6328 

6328 

6308 

6328 


U ) 

6429 

6429 

6409 

6429 


^ / 

652F 

652F 

650F 

652F 


* 

662A 

662A 

660A 

662A 


1 1 

4A2D 

4A2D 

4A1F 

4A2D 


1 + 

4E2B 

4E2B 

4E0B 

4E2B 



712E 

712E 

710E 

712E 


Enter 

720D 

720D 

720A 

720D 


0 

7030 

7030 

7010 

7030 


1 

6D31 

6D31 

6D11 

6D31 


2 

6E32 

6E32 

6E00 

6E32 


3 

6F33 

6F33 

6F13 

6F33 


4 

6A34 

6A34 

6A14 

6A34 


5 

6B35 

6B35 

6B15 

6B35 


6 

6C36 

6C36 

6C1E 

6C36 


7 

6737 

6737 

6717 

6737 


8 

6838 

6838 

6818 

6838 


9 

6939 

6939 

6919 

6939 


Function Keys 




Unshifted 

Shift 

CTRL 

ALT 


FI 

3B00 

5400 

3B00 

3B00 


F2 

3C00 

5500 

3C00 

3C00 


F3 

3D00 

5600 

3D00 

3D00 


F4 

3E00 

5700 

3E00 

3E00 


F5 

3FOO 

5800 

3F00 

3F00 


F6 

4000 

5900 

4000 

4000 


F7 

4100 

5A00 

4100 

4100 


, F8 

4200 

5B00 

4200 

4200 


LJ F9 

4300 

5C00 

4300 

4300 


U ~ J F10 

j | 

4400 

5D00 

4400 

4400 


L-J 

u 






u 






u 
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Appendix C 


Resource Files for 
Sample Programs 




Four of ^ sample programs in this book require re- 
source files in order to run. For those who have resource con- 
struction programs, there is a description of the required 
resource structure after the source code of each program, and, 
in the case of dialog boxes, there will be an illustration of the 
dialog as well. For those who don't have a resource construc- 
tion program, the best advice is to obtain one as quickly as 
possible. In the meantime, however, this appendix presents an 
alternate method of creating the resource files. 

The main program, RSCBUILD.C, merely writes a string 
of bytes to a disk file. The data it writes comes from an array 
called rscdata, which is part of a different file that's #included 
in RSCBUILD.C. The name of this file depends on which re- 
source you wish to build. For example, in order to build 
DIALOG1.RSC, you would #include DIALOGl.DAT in the 
RSCBUILD.C program. To create MENU1.RSC, you would 
type in MENU1.DAT and make sure that file is #included in 
RSCBUILD.C. After you have compiled the program, execute 
it, and it will automatically create the resource file on disk. Be 
careful to type in all of the data for the rscdata array correctly, 
so that the resource structure will be properly recreated. 


Program C-l. rscbuild.c 

/$*$*$$***t**t**********ttt*t**t**tt**t*t**/ 


/* */ 

/* RSCBUILD.C */ 

/* Builds resource -files -for dem */ 

/* ^include the correct -file */ 

/* */ 


/t«****t*tttt*ttt*t*t*t ***************** ***/ 


include <osbind.h> 

^include "di alog 1 . dat " ft substitute the name of the file */ 

ft you're using here */ 


mai n ( ) 
< 


int handle, error; 

handle « Fcreate (FILENAME, 0) ; 
if <handle<0> 

C 

puts ("can't open that file**); 
exit (0) ; 

> 

error = Fwri t© (handl e, FILELEN, rscdatai ; 
printf (** We wrote */.d bytesVn” , error ) ; 

Fc 1 ose ( hand l e ) ; 
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Program C-2. dialog Ldat 

fttttttttttttttttttttttttttttttttttttttttttf 


ft */ 

ft DIALCGl.DAT */ 

ft Data for dialogl.rsc tf 

ft ^Include with RSCBUILD.C */ 

/* */ 


fttttttttttttttttttttttttttttttttttttttttttf 

#def ine FILENAME "DIALQGl.RSC" 

^define FILELEN 1294L 


int rscdataC6473 = 
i 

0x0001 p 0X01A6, 

0X018A, 

0X018A, 

0X018A, 

0X018A, 

0x0024, 

0X018A, 

0X018A, 

0x0506, 

0x0024, 

0x0002, 

0X0001, 

0X0000, 

0X0000, 

0X0000, 

0X0000, 

0X050E, 

0X5F5F, 

0X5F5F, 

0X5F5F, 

0X5F5F, 

0X5F5F, 

0X5F5F, 

0X004F, 

0x7468, 

0x6572, 

0X3A20, 

0X5F5F, 

0X5FSF, 

0X5FSF, 

0x5F5F, 

0x5F5F, 

0X5F5F, 

0X006E, 

0X6E6E, 

0X6E6E, 

0X6E6E, 

0x6E6E, 

0X6E6E, 

0x6E00, 

0X434F, 

0x4D50, 

0x5554, 

0x4552, 

0x2053, 

0x5552, 

0x5645, 

0x5900, 

0X556E, 

0x6465, 

0x7220, 

0x3136, 

0x0031, 

0x3620, 

0x3339, 

0X004F, 

0x7665, 

0x7220, 

0x3339, 

0X0041, 

0x6765, 

0X3A00, 

0X436F, 

0x6070, 

0x7574, 

0x6572, 

0x7320, 

0X4F77, 

0X6E65, 

0X643A, 

0x0041, 

0x7461, 

0x7269, 

0x2053, 

0x5400, 

0x4174, 

0x6172, 

0x6920, 

0x584C, 

0X2F58, 

0x4500, 

0x4578, 

0x6964, 

0x7920, 

0X536F, 

0X7263, 

0X6S72, 

0x6572, 

0X0043, 

0x616E, 

0x6365, 

0x6C00, 

0X4F4B, 

0x0020, 

0x4465, 

0x736B, 

0x2000, 

0x2046, 

0X696C, 

0x6520, 

0x0020, 

0x2054, 

0x6869, 

0x7320, 

0x5370, 

0x6163, 

0x6520, 

0X466F, 

0x7220, 

0x5265, 

0X6E74, 

0X002D, 

0X2D2D, 

0x2020, 

0x2020, 

0x2020, 

0x2020, 

0x2020, 

0x2020, 

0X2D2D, 

0X2D2D, 

0x2020, 

0x2020, 

0x0020, 

0x2044, 

0x6573, 

0X6B20, 

0x4163, 

0x6365, 

0x7373, 

0X6F72, 

0x7920, 

0x3120, 

0x2000, 

0x2020, 

0x4465, 

0X736B, 

0x2041, 

0x6363, 

0x6573, 

0X736F, 

0x7279, 

0x2032, 

0x2020, 

0x0020, 

0X2044, 

0X6573, 

0X6B20, 

0x4163, 

0x6365, 

0x7373, 

0X6F72, 

0x7920, 

0x3320, 

0x2000, 

0x2020, 

0x4465, 

0X736B, 

0x2041, 

0x6363, 

0x6573, 

0x736F, 

0x7279, 

0x2034, 

0x2020, 

0x0020, 

0x2044, 

0x6573, 

0X6B20, 

0x4163, 

0x6365, 

0x7373, 

0X6F72, 

0x7920, 

0x3520, 

0x2000, 

0x2020, 

0x4465, 

0X736B, 

0x2041, 

0x6363, 

0x6573, 

0x736F, 

0x7279, 

0x2036, 

0x2020, 

0x0020, 

0x2053, 

0x7572, 

0x7665, 

0X792E, 

0X2E2E, 

0x0020, 

0x2051, 

0x7569, 

0x7400, 

0X0000, 

0x0024, 

0X0000, 

0x0031, 

0X0000, 

0x0045, 

0x0003, 

0x0006, 

0X0000, 

0x1180, 

0X0000, 

0XFFFF, 

0X000D, 

0x0014, 

0xFFFF, 

0X0001, 

0X0011, 

0x0014, 

0X0000, 

0x0010, 

0x0002, 

0x1100, 

0x0003, 

0X0000, 

0x0027, 

0x0813, 

0x0002, 

0XFFFF, 

0XFFFF, 

0x0010, 

0X0008, 

0X0000, 

0X0000, 

0X018A, 

0x0000, 

0X000E, 

0x0013, 

0X0001, 

0x0003, 

0xFFFF, 

0XFFFF, 

0X001C, 

0X0000, 

0X0000, 

0X0000, 

0x0052, 

0X0010, 

0X0001, 

0X000F, 

0X0001, 

0x0007, 

0x0004, 

0x0006, 

0x0019, 

0X0000, 

0X0000, 

0X0000, 

0x1100, 

0x0007, 

0x0004, 

0X001B, 

0X0001, 

0x0005, 

0xFFFF, 

0XFFFF, 

0X001A, 

0X0011, 

0X0000, 

0X0000, 

0x0062, 

0X0000, 

0X0000, 

0x0009, 

0X0001, 

0X0006, 

0XFFFF, 

0XFFFF, 

0X001A, 

0X0011, 

0X0000, 

0X0000, 

0X006B, 

0X000A, 

0X0000, 

0x0008, 

0X0001, 

0x0003, 

0XFFFF, 

0XFFFF, 

0X001A, 

0X0011, 

0X0000, 

0X0000, 

0x0071, 

0X0013, 

0X0000, 

0x0008, 

0X0001, 

0x0008, 

0xFFFF, 

0XFFFF, 

0x0010, 

0X0000, 

0X0000, 

0X0000, 

0x0079, 

0x0002, 

0x0004, 

0x0004, 

0X0001, 

0x0009, 

0x FFFF , 

0xFFFF, 

0X001C, 

0X0000, 

0X0000, 

0X0000, 

0X007E, 

0x0002, 

0x0006, 

0X0010, 

0X0001, 

0X000A, 

0xFFFF, 

0x FFFF, 

0x0014, 

0X0001, 

0X0000, 

0X00FF, 

0x1101, 

0x0007, 

0x0008, 

0x0003, 

0X0001, 

0X000B, 

0x FFFF , 

0xFFFF, 

0x0014, 

0X0001, 

0X0000, 

0X00FF, 

0x1101, 

0x0007, 

0X000A, 

0X0003, 

0X0001, 

0X000C, 

0xFFFF, 

0XFFFF, 

0x0014, 

0X0001, 

0X0000, 

0X00FF, 

0x1101, 

0x0007, 

0X000C, 

0X0003, 

0X0001, 

0X000D, 

0XFFFF, 

0XFFFF, 

0x0014, 

0X0001, 

0X0000, 

0x00 FF, 

0x1101, 

0x0007, 

0X000E, 

0x0003, 

0X0001, 

0X000E, 

0xFFFF, 

0xFFFF, 

0X001C, 

0X0000, 

0X0000, 

0X0000, 

0X008F, 

0x0000, 

0x0008, 

0x0008, 

0X0001, 

0X000F, 

0x FFFF, 

0XFFFF, 

0X001C, 

0X0000, 

0X0000, 

0X0000, 

0x0098, 

0X000C, 

0x000 A, 

0X000B, 

0X0001, 

0X0010, 

0XFFFF, 

0XFFFF, 

0X001C, 

0X0000, 

0X0000, 

0X0000, 

0X00A4, 

0x0000, 

0X000C, 

0X000E, 

0X0001, 

0X0011, 

0x FFFF , 

0xFFFF, 

0X001A, 

0x0005, 

0X0000, 

0X0000, 

0X00B3, 

0x0004, 

0X0011, 

0x0008, 

0X0001, 

0X0000, 



n 

n 



n 

n 

n 

n 
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0xFFFF, 

0x0011, 

0x0000, 

0x0002, 

0x0000, 

0x0000, 

0xFFFF, 

0x0000, 

0x0000, 

0x0006, 

0x0301, 

0x0000, 

0XFFFF, 

0x0000, 

0x0008, 

0XFFFF, 

0x0002, 

0x0000, 

0XFFFF, 

0x0004, 

0x0000, 

0xFFFF, 

0x0006, 

0x0000, 

0x0010, 

0x0000, 

0x0000, 

0xFFFF, 

0x0001, 

>1 


0xFFFF, 

0x0008, 

0x0000, 

0x0002, 

0x0050, 

0x0000, 

0xFFFF, 

0x0006, 

0x0000, 

0X000F, 

0x0050, 

0X00FF, 

0xFFFF, 

0x0017, 

0x0000, 

0XFFFF, 

0x0017, 

0x0000, 

0xFFFF, 

0x0017, 

0x0000, 

0xFFFF, 

0x0017, 

0x0000, 

0x0011, 

0X000D, 

0x0000, 

0xFFFF, 

0X000D, 


0X001A, 

0x0001, 

0x0000, 

0x0014, 

0x0201, 

0x0000, 

0x0020, 

0x0301, 

0X00C4, 

0x0019, 

0x0013, 

0x1100, 

0X001C, 

0x0001, 

0X00E1, 

0X001C, 

0x0001, 

0X010E, 

0X001C, 

0x0001, 

0x0138, 

0X001C, 

0x0001, 

0x0162, 

0x0014, 

0x0002, 

0x0177, 

0X001C, 

0x0001, 


0x0027, 

0XFFFF, 

0x0000, 

0x0000, 

0x0001, 

0x0002, 

0x0000, 

0x0002, 

0x0006, 

0x0000, 

0X000F, 

0X0002, 

0X0000, 

0x0009, 

0x0000, 

0x0000, 

0X000B, 

0x0000, 

0x0000, 

0X000D, 

0x0000, 

0x0000, 

0x0006, 

0x0000, 

0x0000, 

0x0011, 

0x0000, 

0x0020, 

0X0000, 


0X0000, 

0X0001, 

0X0000, 

0X0000, 

0x0003, 

0x0000, 

0x0000, 

0XFFFF, 

0x0000, 

0x0000, 

0x0007, 

0x0000, 

0x0000, 

0XFFFF, 

0x0001, 

0x0000, 

0xFFFF, 

0x0003, 

0x0000, 

0XFFFF, 

0x0005, 

0x0000, 

0xFFFF, 

0x0007, 

0x0000, 

0xFFFF, 

0x0000, 

0x0000, 

0X01A6, 


0x0000, 

0x0005, 

0x0050, 

0x0000, 

0x0004, 

0X000C, 

0x0000, 

0>:FFFF, 

0x0006, 

0X0000, 

0X000E, 

0x0017, 

0x0000, 

0XFFFF, 

0x0017, 

0x0000, 

0xFFFF, 

0x0017, 

0x0000, 

0xFFFF, 

0x0017, 

0x0000, 

0xFFFF, 

0x0017, 

0X00FF, 

0XFFFF, 

0x0000, 

0x0000, 

0x0000, 


0X00BA, 

0x0019, 

0x0019, 

0x1100, 

0x0019, 

0X0301, 

0X00BD, 

0x0020, 

0x0301, 

0x0000, 

0x0014, 

0X0008, 

0X00CB, 

0X001C, 

0x0001, 

0X00F9, 

0X001C, 

0x0001, 

0x0123, 

0X001C, 

0x0001, 

0X014D, 

0X001C, 

0x0001, 

0x1100, 

0X001C, 

0x0001, 

0x0183, 

0x0356 


0X001B, 

0x0000, 

0x0005, 

0x0000, 

0x0000, 

0x0004, 

0x0000, 

0x0000, 

0x0000, 

0x0000, 

0x0000, 

0x0008, 

0X0000, 

0X0000, 

0X000A, 

0X0000, 

0x0000, 

0X000C, 

0x0000, 

0x0000, 

0X000E, 

0x0000, 

0x0000, 

0x0005, 

0x0008, 

0x0000, 

0X000F, 

0x0000, 


Program 2a. dialogl.h 

ft resource set indices for DIAL0G1 */ 


U 

u 


•def ine 

DIALTREE 

0 

/* 

form/dialog tf 



•def ine 

OTHERTXT 

1 

/% 

FTEXT in tree DIALTREE */ 

•define 

YUNGBUTN 

4 

ft 

BUTTON 

in 

tree 

DIALTREE 

*/ 

•def ine 

MIDBUTN 

5 

ft 

BUTTON 

in 

tree 

DIALTREE 

*/ 

•define 

OLDBUTN 

6 

ft 

BUTTON 

in 

tree 

DIALTREE 

*/ 

•define 

STBOX 

9 

ft 

BOX in 

tree DIALTREE */ 


•define 

XLBOX 

10 

ft 

BOX in 

tree DIALTREE tf 


•define 

EXIDYBOX 

11 

ft 

BOX in 

tree DIALTREE */ 


•define 

OTHERBOX 

12 

ft 

BOX in 

tree DIALTREE */ 


•define 

CANBUTN 

16 

ft 

BUTTON 

in 

tree 

DIALTREE 

*/ 

•define 

OKBUTN 

17 

ft 

BUTTON 

in 

tree 

DIALTREE 

*/ 

•define 

MENUTREE 

1 

ft 

menu tree 

*/ 



•define 

SURVITEM 

16 

ft 

STRING 

in 

tree 

MENUTREE 

*/ 

•define 

GUITITEM 

17 

ft 

STRING 

in 

tree 

MENUTREE 

*/ 
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Program C-3. dialog2.dat 

/******************** ************ **********/ 


/* */ 

/* DIAL0S2.DAT */ 

/* Data for dialog2.rsc */ 

/* ^include with RSCBUILD.C */ 

/* */ 


/* ****** ************************* **********/ 

•define FILENAME '’DIAL0G2.RSC" 

•define FXLELEN 410L 

int rscdataC2053 = 




0X0001 , 

0x0076, 

0X005 A, 

0x0076, 

0X005A, 

0x005 A, 

0x0024, 

0x005 A 

0X005A, 

0x0196, 

0X000C, 

0X0001, 

0X0001, 

0x0000, 

0x0000, 

0x0000 

0x0000, 

0X019A, 

0x4558, 

0x4954, 

0x0020, 

0x2020, 

0x 3000, 

0x0000 

0>:536C, 

0x6964, 

0x6572, 

0x 2050 , 

0X6F73, 

0x6974, 

0x696F, 

0X6E3A 

0X004F, 

0xS0S4, 

0x494F, 

0x4E31, 

0X004F, 

0x5054, 

0x494F, 

0x4E32 

0X004F, 

0x3054, 

0x494F, 

0X4E33, 

0x0050, 

0X0000, 

0x0029, 

0x0000 

0X002E, 

0x0000, 

0X002F, 

0x0003, 

0x0006, 

0X0000, 

0x1180, 

0x0000 

0XFFFF, 

0X000S, 

0X0001 , 

0XFFFF, 

0x0001 , 

0X0006, 

0x0014, 

0x0000 

0X0010, 

0x0002, 

0x1100, 

0X0001, 

0X0000, 

0x0027, 

0x0012, 

0x0003 

0x0002, 

0x0002, 

0x0014, 

0x0000, 

0X0000, 

0X00FF , 

0x1101, 

0x0020 

0x0003, 

0x0002, 

0X000A, 

0x0001, 

0xFFFF, 

0xFFFF, 

0x0014, 

0x0040 

0x0000, 

0x0001 , 

0X1171, 

0x0000, 

0x0000, 

0x0002, 

0x0001 , 

0x 0004 

0XFFFF, 

0xFFFF, 

0x001 A, 

0x0007, 

0X0000, 

0X0000, 

0x0024, 

0x0012 

0X000F , 

0x0008, 

0X0001, 

0x0005, 

0xFFFF, 

0xFFFF, 

0x0015, 

0X0000 

0x0000, 

0x0000, 

0X00SA, 

0x0019, 

0x0003, 

0X0004, 

0x0001 , 

0x0006 

0>:FFFF, 

0XFFFF, 

0X001C, 

0X0000, 

0X0000, 

0x0000, 

0x0030, 

0X000D 

0X0001, 

0X0010, 

0X0001 • 

0x0007, 

0xFFFF, 

0XFFFF, 

0x00 1C, 

0x0000 

0X0000, 

0x0000, 

0x0041 , 

0x000 A, 

0:;0005, 

0x0007, 

0X0001, 

0x0008 

0xFFFF, 

0xFFFF, 

0>:00 1C, 

0x0000, 

0>:0000, 

0X0000, 

0x0049, 

0X000A 

0x0008, 

0x 0007 , 

0x0001 , 

0x0009, 

0xFFFF, 

0xFFFF , 

0x001 C, 

0X0000 

0X0000, 

0X0000, 

0x0051 , 

0X0O0A, 

0x0008, 

0x0007, 

0X0001 , 

0X000A 

0XFFFF, 

0xFFFF, 

0x0014, 

0X0001, 

0X0000, 

0X00FF, 

0x1101, 

0x 0003 

0X0004, 

0x0006, 

0x0003, 

0X000B, 

0xFFFF, 

ClxFFFF, 

0x0014, 

0X0001 

0X0000, 

0X00FF, 

0x1101, 

0x0003, 

0x0007, 

0x0006, 

0x0003, 

0X0000 

0xFFFF, 

0XFFFF, 

0x0014, 

0x0021, 

0x0000, 

0x00 FF, 

0x1101, 

0x0003, 

0x000 A, 

0x0006, 

0X0003, 

0X0000, 

0x0076 





>5 





Program 3a. diaIog2.h 

/* resource set indices for DIALCG2 */ 



•def ine 

DIALTREE 

0 

/* 

form/dialog 

*/ 


•def ine 

SLIDEBAR 

1 

/* 

BOX 

in 

tree 

DIALTREE 

*/ 

•define 

SLIDER 

2 

/* 

BOX 

in 

tree 

DIALTREE 

*/ 

•define 

EXITBUTN 

3 

/* 

BUTTON 

in tree DIALTREE 

•define 

NUMBER 

4 

/* 

TEXT in tree DIALTREE */ 

•define 

QPTIGN1 

9 

/* 

BOX 

in 

tree 

DIALTREE 

*/ 

•define 

QPTICN2 

10 

/* 

BOX 

in 

tree 

DIALTREE 

*/ 

•define 

0PTI0N3 

11 

/* 

BOX 

in 

tree 

DIALTREE 

*/ 




n 

n 
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Resource Files for Sample Programs 





Program C-4. menul.dat 

/tiMtmtumtmmtttmummtmtu/ 


ft 


*/ 

ft 

KENU1.DAT 

*/ 

ft 

Data for menul.rsc 

*/ 

ft 

♦include with RSCBUILD.C 

*/ 

ft 


*/ 


/tttmtMtttMMmmtmmmmtumt/ 

♦define FILENAME "MENU1.RSC” 

♦define FILELEN 1026L 







int rscdataC5133 n 
C 


0x0001 f 

0X01A6, 

0X01A6, 

0X01A6, 

0X01A6, 

0X01A2, 

0x0024, 

0X01A2 

0x0 1A6, 

0X03FE, 

0x0019, 

0X0001, 

0X0000, 

0x0000, 

0X0000, 

0X0001 

0X0000, 

0x0402, 

0x2044, 

0x6573, 

0X6B20, 

0x0020, 

0x4669, 

0X6C65 

0x2000, 

0x2044, 

0x7261, 

0x7720, 

0x0020, 

0x2041, 

0X626F, 

0x7574 

0X204D, 

0X656E, 

0x7531, 

0X2E2E, 

0X2E00, 

0X2D2D, 

0X2D2D, 

0x2020 

0X2D2D, 

0x2020, 

0x2020, 

0X2D2D, 

0X2D2D, 

0x2020, 

0X2D2D, 

0x2020 

0x0020, 

0x2044, 

0x6573, 

0X6B20, 

0x4163, 

0x6365, 

0x7373, 

0X6F72 

0x7920, 

0x3120, 

0x2000, 

0x2020, 

0x4465, 

0X736B, 

0x2041, 

0x6363 

0x6373, 

0X736F, 

0x7279, 

0x2032, 

0x2020, 

0x0020, 

0x2044, 

0x6573 

0x6B20, 

0x4163, 

0x6365, 

0x7373, 

0X6F72, 

0x7920, 

0x3320, 

0x2000 

0x2020, 

0x4465, 

0x736B, 

0x2041, 

0x6363, 

0x6573, 

0x736F, 

0x7279 

0x2034, 

0x2020, 

0x0020, 

0x2044, 

0x6573, 

0x6B20, 

0x4163, 

0x6365 

0x7373, 

0X6F72, 

0x7920, 

0x3520, 

0x2000, 

0x2020, 

0x4465, 

0X736B 

0x2041, 

0x6363, 

0x6573, 

0X736F, 

0x7279, 

0x2036, 

0x2020, 

0x0020 

0x2051, 

0X7S69, 

0x7420, 

0X205E, 

0x5100, 

0x2020, 

0x5061, 

0x7474 

0x6572, 

0X6E20, 

0x3120, 

0X5B46, 

0x3150, 

0x0020, 

0x2050, 

0x6174 

0x7465, 

0X726E, 

0x2032, 

0X205B, 

0x4632, 

0X5D00, 

0X5B30, 

0X5D5B 

0x2040, 

0X656E, 

0x7520, 

0x6465, 

0X6D6F, 

0x2077, 

0x6974, 

0x6820 

0x6075, 

0X6C74, 

0X692D, 

0X6F62, 

0X6A65, 

0x6374, 

0X7C20, 

0x6974 

0x6560, 

0x7320, 

0X616E, 

0x6420, 

0x6B65, 

0x7962, 

0x6F61, 

0x7264 

0X2065, 

0x7175, 

0x6976, 

0x6160, 

0x656E, 

0x7473, 

0x7C20, 

0x2020 

0x2020, 

0x2053, 

0X6S6C, 

0x6563, 

0x7420, 

0x2251, 

0x7569, 

0x7422 

0x2074, 

0X6F20, 

0X656E, 

0X642E, 

0X7C2D, 

0X2D2D, 

0X2D2D, 

0X2D2D 

0X2D2D, 

0X2D2D, 

0x2020, 

0X2D2D, 

0X2D2D, 

0X2D2D, 

0X2D2D, 

0X2D2D 

0x2020, 

0X2D2D, 

0x2020, 

0x2D2D, 

0X2D2D, 

0X2D5D, 

0X5B49, 

0X276C 

0X6C20, 

0x7265, 

0x6065, 

0x6062, 

0x6572, 

0x2074, 

0x6861, 

0x7450 

0x0065, 

0x0000, 

0X010C, 

0XFFFF, 

0X0001, 

0x0006, 

0x 0019, 

0X0000 

0X0000, 

0X0000, 

0X0000, 

0X0000, 

0X0000, 

0x0050, 

0x0019, 

0x0006 

0x0002, 

0x0002, 

0x0014, 

0X0000, 

0X0000, 

0X0000, 

0x1100, 

0X0000 

0X0000, 

0x0050, 

0x0201, 

0X0001, 

0x0003, 

0x0005, 

0x0019, 

0X0000 

0X0000, 

0X0000, 

0X0000, 

0x0002, 

0X0000, 

0x0012, 

0x0301, 

0x0004 

0xFFFF, 

0xFFFF, 

0x0020, 

0X0000, 

0X0000, 

0X0000, 

0x0024, 

0X0000 

0X0000, 

0x0006, 

0x0301, 

0x0005, 

0xFFFF, 

0xFFFF, 

0x0020, 

0X0000 

0X0000, 

0x0000, 

0X002B, 

0x0006, 

0x0000, 

0x0006, 

0x0301, 

0x0002 

0xFFFF, 

0xFFFF, 

0x0020, 

0X0000, 

0X0000, 

0X0000, 

0x0032, 

0X000C 

0X0000, 

0x0006, 

0x0301, 

0X0000, 

0x0007, 

0x0012, 

0x0019, 

0X0000 

0X0000, 

0X0000, 

0X0000, 

0X0000, 

0x0301, 

0x0050, 

0x0013, 

0X0010 

0x0008, 

0X000F, 

0x0014, 

0X0000, 

0X0000, 

0X00FF , 

0x1100, 

0x0002 

0X0000, 

0x0016, 

0x0008, 

0x0009, 

0XFFFF, 

0XFFFF, 

0X001C, 

0x0000 

0X0000, 

0X0000, 

0x0039, 

0X0000, 

0X0000, 

0x0016, 

0X0001, 

0X000A 

0XFFFF, 

0XFFFF, 

0X001C, 

0X0000, 

0x0008, 

0X0000, 

0X004A, 

0X0000 

0X0001, 

0X0016, 

0X0001, 

0X000B, 

0XFFFF, 

0xFFFF, 

0X001C, 

0X0000 

0X0000, 

0X0000, 

0x0061, 

0X0000, 

0x0002, 

0X0016, 

0X0001, 

0X000C 

0XFFFF, 

0XFFFF, 

0X001C, 

0X0000, 

0X0000, 

0X0000, 

0X0076, 

0X0000 

0x0003, 

0x0016, 

0X0001, 

0x0000, 

0x FFFF, 

0xFFFF, 

0X001C, 

0X0000 

0X0000, 

0X0000, 

0X008B, 

0X0000, 

0x0004, 

0x0016, 

0X0001, 

0X000E 

0XFFFF, 

0XFFFF, 

0X001C, 

0X0000, 

0X0000, 

0X0000, 

0X00A0, 

0X0000 

0x0005, 

0x0016, 

0X0001, 

0X000F, 

0xFFFF, 

0xFFFF, 

0x00 1C, 

0X0000 

0X0000, 

0X0000, 

0X00BS, 

0X0000, 

0x0006, 

0x0016, 

0X0001, 

0x0007 

0XFFFF, 

0XFFFF, 

0X001C, 

0X0000, 

0X0000, 

0X0000,' 

0X00CA, 

0X0000 

0x0007, 

0x0016, 

0X0001, 

0x0012, 

0X0011, 

0X0011, 

0x0014, 

0x0000 

0X0000, 

0X00FF, 

0x1100, 

0x0008, 

0X0000, 

0X000C, 

0X0001, 

0X0010 

0xFFFF, 

0XFFFF, 

0X001C, 

0X0000, 

0X0000, 

0x0000, 

0X00DF, 

0X0000 

0X0000, 

0X000C, 

0X0001, 

0x0006, 

0x0013, 

0x0018, 

0x0014, 

0X0000 


i 
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0x0000, 0X00FF, 
0xFFFF, 0xFFFF, 
0x0000, 0x0010, 
0x0000, 0X00FF, 
0Y.FFFF, 0>:FFFF, 
0X0001, 0X0010, 
0x0000, 0X00FF, 
0>;FFFF , 0xFFFF, 
0x0000, 0x0015, 
0X0000, 0X0000, 
0x0 1A6 
>; 


0x1000, 0X000E, 
0x00 1C, 0x0000, 
0x0001, 0x0015, 
0x1162, 0x0010, 
0X001C, 0x0000, 
0y,000 1 , .0x0017, 
0x1153, 0x0010, 
0x0019, 0x0000, 
0x0001, 0x0012, 
0x1100, 0x0000, 


0x0000, 0x0015, 
0x0000, 0x0000, 
0XFFFF, 0xFFFF, 
0x0000, 0x0005, 
0x0000, 0x0000, 
0xFFFF, 0xFFFF, 
0x0001, 0x0005, 
0X0000, 0X0000, 
0XFFFF, 0xFFFF, 
0x0001, 0x0015, 


0x0002, 0x0014, 
0X00EA, 0x0000, 
0x0014, 0x0000, 
0x0001, 0x0016, 
0X00FB, 0x0000, 
0x0014, 0x0000, 
0x0001, 0x0018, 
0x1100, 0x0000, 
0x0019, 0x0020, 
0x0001, 0x0000, 


n 

n 

n 


Program 4a. menul.h 

/* resource set indices for MENU1 */ 


•define MENUTREE 0 /* 
•define DESKTITL 3 /* 
•define FILETITL 4 /* 
•d*fina DR AWT I TL 5 /* 
•define ABOTITEM 8 /* 
•define QUITITEM 17 /* 
•define DRAWPAT 1 19 /* 
•define PAT1ITEM 23 /* 
•define PAT2ITEM 24 /* 

•define ABT ALERT 0 /* 


menu tree */ 

TITLE in tree MENUTREE */ 
TITLE in tree MENUTREE */ 
TITLE in tree MENUTREE */ 
STRING in tree MENUTREE */ 
STRING in tree MENUTREE */ 
STRING in tree MENUTREE */ 
I BOX in tree MENUTREE */ 
IBOX in tree MENUTREE */ 

Alert string index */ 


Program C-5, menu2.dat 
/******************************************/ 


/* */ 

/* MENU2.DAT */ 

/* Data for menu2.rsc */ 

/* •include with RSCBUILD.C */ 

/* */ 


/******************************************/ 

•define FILENAME "MENU2.RSC" 

•define FILELEN 1068L 


int rscdataC5343 = 


0x0001, 0x0200, 0X0200, 0x0200, 
0x0200, 0x0428, 0x0017, 0x0001, 
0X0000, 0X042C, 0x2044, 0x6573, 
0x2000, 0x204F, 0x7074, 0x696F, 
0X6F75, 0x7420, 0x4065, 0x6E75, 
0X2D2D, 0x2D2D, 0x2D2D, 0x2D2D, 
0x2D2D, 0x2D00, 0x2020, 0x4465, 
0X736F, 0x7279, 0x2031, 0x2020, 
0x4163, 0x6365, 0x7373, 0x6F72, 
0x4465, 0X736B, 0x2041, 0x6363, 
0x2020, 0x0020, 0x2044, 0x6573, 
0X6F72, 0x7920, 0x3420, 0x2000, 
0x6363, 0x6573, 0X736F, 0x7279, 
0x6573, 0X6B20, 0x4163, 0x6365, 
0x2000, 0x2020, 0x5175, 0x6974, 
0x6865, 0X636B, 0x204D, 0x6172, 
0x2D2D, 0x2D2D, 0X2D2D, 0x2D2D, 
0x0020, 0x2054, 0x7572, 0x6E20, 
0x6020, 0X4F4E, 0x2000, 0x2020, 
0x7373, 0x6167, 0x6500, 0x2020, 
0x7420, 0x4974, 0x6560, 0x204F, 
0x4065, 0X6E75, 0x2064, 0x6560, 


0x0200, 0X01F4, 0x0024, 0X01F4, 
0x0000, 0x0000, 0x0000, 0x0003, 
0X6B20, 0x0020, 0x4669, 0x6C65, 
0X6E73, 0x2000, 0x2020, 0x4162, 
0X322E, 0x2E2E, 0x0020, 0x2D2D, 
0x2020, 0x2020, 0x2020, 0x2D2D, 
0X736B, 0x2041, 0x6363, 0x6573, 
0X0020, 0x2044, 0x6573, 0X6B20, 
0x7920, 0x3220, 0x2000, 0x2020, 
0x6573, 0x736F, 0x7279, 0x2033, 
0X6B20, 0x4163, 0x6365, 0x7373, 
0x2020, 0x4465, 0x736B, 0x2041, 
0x2035, 0x2020, 0x0020, 0x2044, 
0x7373, 0x6F72, 0x7920, 0x3620, 
0x2020, 0X5E51, 0x0020, 0x2043, 
0X6B00, 0x2020, 0x2020, 0x2020, 
0X2D2D, 0X2D2D, 0x2020, 0X2D2D, 
0X4E65, 0x7874, 0x2049, 0x7465, 
0x5072, 0X696E, 0x7420, 0x4065, 
0x5475, 0x726E, 0x204E, 0x6578, 
0x4646, 0X005B, 0x3050, 0x5B20, 
0X6F20, 0x7769, 0x7468, 0x2063, 


n 

n 

n 

n 

n 
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Resource Files for Sample Programs 


U 

u 

u 


0x6865, 

0x7969, 

0x6174, 

0x5365, 

0x2065, 

0X2D2D, 

0X2D2D, 

0x656D, 

0x5475, 

0x4E20, 

0XFFFF, 

0x0000, 

0x0000, 

0x0001, 

0x0002, 

0x0000, 

0x0005, 

0x0006, 

0x0000, 

0x0000, 

0x0000, 

0x0000, 

0x0009, 

0x0000, 

0x0000, 

0X000B, 

0x0000, 

0x0000, 

0X000D, 

0x0000, 

0x0000, 

0X000F, 

0x0000, 

0x0000, 

0x0012, 

0x0008, 

0x0000, 

0x0006, 

0X000E, 

0x0000, 

0x0015, 

0x0000, 

0x0000, 

0x0012, 

0x0000, 


0X636B, 
0X6E67, 
0x6520, 
0X6C6S, 
0X6E64, 
0X2D2D, 
0X2D2D, 
0x6560, 
0X726E, 
0x0000, 
0x0001, 
0x0000, 
0x0000, 
0x0003, 
0x0000, 
0x0000, 
0xFFFF, 
0x0000, 
0x0000, 
0x0007, 
0x0301, 
0x0000, 
0XFFFF, 
0x0000, 
0X0008, 
0x FFFF , 
0x0002, 
0x0000, 
0XFFFF, 
0x0004, 
0x0000, 
0XFFFF, 
0x0006, 
0x0000, 
0x0011, 
0x0000, 
0x0000, 
0x0013, 
0x0000, 
0x0000, 
0xFFFF, 
0x0001, 
0x0000, 
0XFFFF, 
0x0003, 


0x2060, 
0X2C20, 
0x7465, 
0x6374, 
0X2E7C, 
0X2D2D, 
0x2D2D, 
0x6265, 
0X204E, 
0x0000, 
0x0006, 
0x0050, 
0x0000, 
0x0005, 
0x0016, 
0x0000, 
0xFFFF, 
0x0006, 
0X0000, 
0x0012, 
0x0050, 
0X00FF, 
0XFFFF, 
0x0016, 
0x0000, 
0xFFFF, 
0x0016, 
0x0000, 
0xFFFF, 
0x0016, 
0x0000, 
0XFFFF, 
0x0016, 
0x 0000, 
0x0011, 
0X000C, 
0x0000, 
0x0016, 
0x0016, 
0x0000, 
0xFFFF, 
0x0016, 
0x0000, 
0x FFFF, 
0x0016, 


0x6172, 
0X616E, 
0x7874, 
0x2022, 
0x2020, 
0x2D2D, 
0X2D2D, 
0x7220, 
0x6578, 
0x0136, 
0x0019, 
0X0019, 
0x1100, 
0x0019, 
0x0301 , 
0x0024, 
0x0020, 
0x0301, 
0x0032, 
0x0019, 
0x0013, 
0x1100, 
0X001C, 
0x0001, 
0x0040, 
0X001C, 
0x0001, 
0x0079, 
0X001C, 
0x0001, 
0x00 A3, 
0X001C, 
0x0001, 
0X00CD, 
0x0014, 
0x0001, 
0X00E2, 
0x0014, 
0x0004, 
0X00ED, 
0X001C, 
0x0001, 
0x0111, 
0x00 1C, 
0x0001, 


0x6873, 

0x6420, 

0X2E7C, 

0x5175, 

0X2D2D, 

0x2D2D, 

0X5D5B, 

0x7468, 

0x7420, 

0x0000, 

0x0000, 

0x0006, 

0X0000, 

0x0000, 

0x0004, 

0x0000, 

0X0000, 

0x0002, 

0X000C, 

0x0000, 

0X0010, 

0x0002, 

0X0000, 

0X000A, 

0x0000, 

0x0000, 

0X000C, 

0x0000, 

0x0000, 

0X000E, 

0x0000, 

0x0000, 

0x0007, 

0x0000, 

0x0000, 

0x0010, 

0x0000, 

0x0000, 

0x0014, 

0x0000, 

0x0000, 

0x0016, 

0X0000, 

0x0020, 

0x0000, 


0X2C7C, 
0X616C, 
0x2020, 
0x6974, 
0x2020, 
0x2D2D, 
0x4927, 
0x6174, 
0x4974, 
0x0 14B, 
0x0000, 
0x0002, 
0x0000, 
0x0000, 
0xFFFF, 
0x0000, 
0X0000, 
0XFFFF, 
0x0000, 
0x0000, 
0x0008, 
0x0000, 
0x0000, 
0xFFFF, 
0x0001, 
0x0000, 
0xFFFF, 
0x0003, 
0x0000, 
0xFFFF, 
0x0005, 
0x0000, 
0XFFFF, 
0X0007, 
0x0000, 
0XFFFF, 
0x0000, 
0x0000, 
0XFFFF, 
0x0000, 
0x0008, 
0xFFFF, 
0x0002, 
0X0008, 
0x0200 


0x2067, 
0x7465, 
0x2020, 
0x2220, 
0X2D2D, 
0X2D2D, 
0x6C6C, 
0x5000, 
0X656D, 
0x0000, 
0x0000, 
0x0002, 
0x0050, 
0x0000, 
0xFFFF, 
0x0006, 
0X0000, 
0x FFFF, 
0X000A, 
0x0000, 
0X000F , 
0x0016, 
0x0000, 
0xFFFF, 
0x0016, 
0x0000, 
0xFFFF, 
0x0016, 
0x0000, 
0xFFFF, 
0x0016, 
0x 0000, 
0XFFFF, 
0X0016, 
0X00FF, 
0x FFFF, 
0X000C, 
0X00FF, 
0XFFFF, 
0x0016, 
0x0000, 
0XFFFF, 
0x0016, 
0x0000, 


0x7261, 
0X726E, 
0x2020, 
0X746F, 
0X2D2D, 
0x2020, 
0x2072, 
0x2020, 
0x204F, 
0X01DE, 
0x0000, 
0x0014, 
0x0201, 
0x0000, 
0x0020, 
0x0301, 
0X002B, 
0X0020, 
0x0301, 
0x0000, 
0x0014, 
0x0008, 
0X003C, 
0X001C, 
0x0001, 
0x0064, 
0X001C, 
0x0001, 
0X008E, 
0X001C, 
0x0001, 
0X00B8, 
0X001C, 
0X0001, 
0x1100, 
0x00 1C,. 
0x0001, 
0x1000, 
0x00 1C, 

0X0001 , 

0X00FA, 

0X001C, 

0x0001, 

0x0126, 



Program Sa. menu2.h 

/% resource set indices for MENU2 */ 






ttdef ine 

MENUTREE 

0 

/* 

menu tree */ 



ttdef ine 

DESKTITL 

3 

/* 

TITLE in tree 1 

MENUTREE 

*/ 

ttdef ine 

FILw TITL 

4 

ft 

TITLE in tree 

MENUTREE 

*/ 

ttdef ine 

OPTNTITL 

5 

ft 

TITLE in tree ! 

MENUTREE 

*/ 

ttdef ine 

ABOTITEM 

8 

/* 

STRING in tree 

MENUTREE 

*/ 

ttdef ine 

QUIT ITEM 

17 

/* 

STRING in tree 

MENUTREE 

*/ 

ttdef ine 

CHEKITEM 

19 

/* 

STRING in tree 

MENUTREE 

*/ 

ttdef ine 

TOOL ITEM 

21 

/* 

STRING in tree 

MENUTREE 

*/ 

ttdef i ne 

ABLE ITEM 

22 

/* 

STRING in tree 

MENUTREE 

*/ 

ttdef ine 

OFFSTRNG 

0 

/* 

Free string index tf 


ttdef ine 

ABTALERT 

1 

/* 

Alert string index t/ 


ttdef i ne 

DNSTRNQ 

2 

ft 

Free string index %/ 
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Function Index 

n 

n 




n 

Function 

Opcode 

Number 

Page 

n 

appLJnit( ) 

10 

21/ 223 

appL_read( ) 

11 

55, 64, 224 

appL-write( ) 

12 

55, 62-63, 225 


appL_Find( ) 

13 

63-64, 226 


appl— tplay( ) 

14 

227 


appl_trecord( ) 

15 

228 


appl_exit( ) 

19 

21, 229 


evnt-keybd( ) 

20 

91, 230 


evnt_button( ) 

21 

88-90, 180, 231-33 


evnt- mouse( ) 

22 

90, 233-34 


evnt—mesag( ) 

23 

54, 64, 235-37 


evnt-.timer( ) 

24 

91-92, 218, 238 


evnt— multi( ) 

25 

53-54, 92-94, 123, 180, 218, 239-41 


evnt_ddick( ) 

26 

88, 242 


menu— bar( ) 

30 

243 


menu— icheck( ) 

31 

244 


menu— ienable( ) 

32 

148, 245 


menu— tnormal( ) 

33 

144, 246 


menu— text( ) 

34 

149-50, 247 


menu— register( ) 

35 

202, 248 


objc— add( ) 

40 

124, 249 


objc-delete( ) 

41 

124, 250 


objc— draw( ) 

42 

60, 119-21, 163, 185, 251 


objc— find( ) 

43 

121, 252 


objc— offset( ) 

44 

121-22, 253 


objc-order( ) 

45 

124, 254 


objc_edit( ) 

46 

122, 255-56 


objc-change( ) 

47 

122, 164, 180, 257 


form— do( ) 

50 

108, 159-61, 163, 180, 218, 258 


form— dial( ) 

51 

161-64, 259-60 


form— alert( ) 

52 

157-58, 261-62 


form— error( ) 

53 

155-57, 263-64 . 

n 

form— center( ) 

54 

161, 265 

form— keybd( ) 

55 

266 ! 

form— butn( ) 

56 

267 


graf— rubberbox( ) 

70 

179-80, 268 . 

n 

graf— dragbox( ) 

71 

180, 269-70 

graf— mbox( ) 

72 

186, 271 1 

graf— growbox( ) 

73 

186-87, 272 


graf— shrinkbox( ) 

74 

186-87, 273 

n 

graf— watchbox( ) 

75 

185-86, 274 1 

graf— slidebox( ) 

76 

180-81, 275 1 

graf— handle( ) 

77 

21, 276 


graf— mouse( ) 

78 

39, 50, 57, 61, 187-88, 277-78 . 

n 

graf— mkstatef ) 

79 

196-97, 279 

scrp— read( ) 

80 

280 1 

scrp_ write( ) 

81 

281 


fsel—input( ) 

90 

170-72, 282-83 

n 
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Function 

Opcode 

Number 

Page 

wind—create( ) 

100 

26-28, 35, 284-85 

wind_open( ) 

101 

27, 31, 33, 286 

wind_close( ) 

102 

34-35, 287 

wind,.delete( ) 

103 

35, 288 

wind_get( ) 

104 

29, 58, 289-90 

wind_set( ) 

105 

31-33, 291-92 

wind—find( ) 

106 

293 

wind_update( ) 

107 

57, 61, 294 

windL_calc( ) 

108 

34, 65, 295-96 

rsrc_load( ) 

110 

135-36, 161, 297 

rsrc_free( ) 

111 

136, 298 

rsrc_gaddr( ) 

112 

136-37, 158, 161, 299-300 

rsrc_saddr( ) 

113 

138-39, 301-2 

rsrc_obfix( ) 

114 

138, 303 

shel_read( ) 

120 

304 

shel_write( ) 

121 

305-6 

sheLJind( ) 

124 

307 

shel_envm( ) 

125 

308 
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Index 


n 

n 

n 


AC-CLOSE 203 
action point. See hot spot 
ACTIVE 140-41 
active window 58 
AES Event Library 53 
AES Graphics Library 8-9, 179-97 
calling routines from C 16-17 
data arrays 10 
graf—mouse 187 
machine language programming 
12-14 

rectangle list 58 
unregistering an application 21 
Alcyon C compiler 17, 132 
alerts 157-59 
creating 158-59 
format 157-58 
NOTE 158 
STOP 158 
APPLBLK 113 
appl_find( ) 63 

Application Environment Services. 4 
Application library 8 
desk accessories 203 
finding memory starting address 47 
layout of Transient Program Area in 
ST memory 48 

opening an output window 23 
program area total size 48 
sending and receiving redraw mes- 
sages 63 

system memory-management calls 
47 

appL_read( ) 55, 64 
appl_write( ) 55, 62-63 
arrow characters 78 
background pens 189 
BAR 140-41 
basepage 47 

Basic Input/Output System. See BIOS 
binary tree 98 

BIOS (Basic Input/Output System) 4-5 
BITBLK 110-11 
bi_color 111 
bi — hi 111 
bi_pdata 111 
bi_wb 111 
bi_x 111 
bi_y 111 
G—1MAGE 110 


bit flags 117-19 
DEFAULT 117 
EDITABLE 119-20 
EXIT 117 
HIDETREE 119 
INDIRECT 119 
LASTOB 118 
RBUTTON 118 
SELECTABLE 117 
TOUCHEXIT 118 
blit 158 

boxes 104, 106, 109-10, 180-82, 
185-86 
borders 106 
border thickness 110 
color 110 
dragging 180 

drawing a moving box 186 
G-BOX 104 
G—BOXCHAR 104 
G—IBOX 104 
growing 186-87 
justifying text 109-10 
monitoring mouse position 185-86 
moving slider object 181 
moving within containers 180-82 
pattern 110 
shrinking 186-87 
specifying text length 110 
character cell 23 
clipping rectangle 60-61, 172 
proceeding to next 61 
setting 60 
close box 25 
color mask 189 
control array 10 
controls 26 

controls input parameter 34 
C programming 21, 39 
incorrect bindings 21 
startup file 39 
Ctrl 50 

data arrays beginning addresses 12 
deallocating memory 47 
desk accessories 201-19 

entering text strings into menu, 202 

loading 201-2 

menu items 202-3 

problems 219 

returning to Desktop 203 

writing 201-3 







n 

n 
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Desk Accessory Buffer 9-10 
DESK conventions 142 
Desktop 9 

Desktop work area 24 
dialog boxes 159-64, 169-70 
animating 159-63 
bugs 169-70 

deselecting exit button 164 
drawing 163 

noting new selection settings 164 
releasing screen area 163-64 
reserving screen area 161-62 
reverse zoom box 163 
zoom box 162 
display screen, locking 57 
DNARROW 78 
double-click 118 
double-click speed setting 88 
drag bar 67 
drop-down menus 140 
dummy 16, 80 
environment services 3 
error box 155 
Event Library 5, 8 
events 92 

evnt_button( ) 88-90 
bug 90 

button variable 89 
clicks 88 
exitbutn 158 

extended BIOS. See XBIOS 
FIFO (First In, First Out) 54 
File Selector 170-75 
choosing files 171 
deleting wildcards 174 
displaying dialog box 171-72 
getting a pathname, 172-74 
getting current directory 173-74 
restoring screen display 1 72 
File Selector Library 8, 155-75 
flag 29-30 
foreground pens 189 
form— dial( ) 161-64 
action flags table 162 
FMD_ FINISH 163 
FMD_ GROW 162-63 
FMD— SHRINK 163 
FMD_ START 162 
forcing a redraw 164 
form_do( ) 108, 159-61 

handling object selection 160-61 
problems 170 
Form Library 8, 155-75 
forms 155-57 
full box 25, 66 
fuller box. See full box 
GB (GEM Base) 14 


G— BOXTEXT 107 
G_BUTTON 107 

GEM (Graphics Environment Manager) 
3-17 

initializing application 21 
registering an application 21 
starting an application 21 
GEM bindings 16-17, 97-128, 142 
calling routines from C 16-17 
conventions 142 
graphic objects 97-128 
GEMDOS 4, 156-57 

conversion table to PC DOS 156-57 
getrez 22 

G_FBOXTEXT 108 
G-FTEXT 108 
G-ICON 111-13 
global array 10-11 
G—PROGDEF 113 
graf_mouse( ) 50, 57, 61, 187-88 
form numbers/macro names (table) 
188 

Graphics Environment Manager. See 
GEM 

graphics interface 3 
Graphics Library 8 
graphics primitives 4 
G-STRING 107 
G-TEXT 107 
G—TITLE 107 

G-USERDEF. See G—PROGDEF 
handle 60 
happened 92 
HEAD link field 99 
HIDETREE 142 

horizontal and/or vertical slide bars 25 
hot spot 188 
HSLIDE 78 
ICONBLK 111-12 
ib_ char 112 
ib_ character 112-13 
ib_hicon 112 
ib_htext 112 
ib_pdata 112 
ib— pmask 112 
ib_ ptext 112 
ib_wicon 112 
ib_wtext 112 
ib— xchar 112 
ib— xicon 112 
ib_xtext 112 
ib_ ychar 112 
ib— yicon 112 
ib_ ytext 112 
icons 111-13 
image mask 111 
information line 25 
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input array 22 
input parameter arrays 12 
integer data type (int). See short 
kernel 5 

keyboard events 91 
K-Resource (KRSC) 132 
LFARROW 78 

Line A graphics routines 4-5 
machine language AES calls 12-14 
macro definitions 55 
Megamax C compiler 17, 132 
Megamax Resource Construction Program 
(MMRCP) 132 
Menu/ Alert Buffer 9 
menu bar 24 
Menu Library 8 
menus 140-52, 148-50 
adding objects 141-42 
changing tree to dialog boxes 141-42 
creating trees 141 
DESK 142 
disabling 148 
drawing menu bar 143 
drop-down 140 
EDIT 142 
RLE 142 

finding current settings 149-50 
getting tree address 143 
installing 143 
mouse selection 140 
return title to normal video 144 
using 143-44 
MENUTREE 143 
message pipe 54, 64 
messages 53-78 
format 54-55 
predefined messages 55 
reading directly 64 
reading pipe directly 64 
refresh messages 56-62 
sending 62-64 
sending longer messages 55 
sending to other applications 63-64 
sending to your own application 63 
waiting for 64 
window 64-78 
MN-SELECTED 143, 202-3 
modeless programs 170 
mouse 57, 61, 88-91, 187-88, 196 
button events 88 
changing click speeds 88 
changing forms 187 
checking current status 196 
form definition data structure (table) 
188 

rectangle events 90-91 
turning off 57 


turning on 61 

waiting for button event 88-89 
move bar 25 
moving windows 67 
msgbuf array 54 
multiple events 92-94 
multitasking 5-6 
breakdown 6 
newpos 124 
NEXT field 98 
Not-Ready list 5 
OBDEFS.H header file 97 
ob_head 98 
Object Library 8 
routines 120-25 
object number 98 
objects 97-128 
bit image 110-13 
changing sibling order 124 
changing status field 122 
children 98 
color 104-5 
color tables 105 
colored text string 107 
creating data 131 
deleting from tree 124 
drawing trees 102, 120-21 
finding absolute screen position 
121-22 

finding index numbers from coordi- 
nates 121 

finding overlapping rectangles 101-2 

flags 115-19 

formatted text 107-10 

formatted text borders 107 

icons 111-13 

parents 98 

position 101-2 

sample tree 101-2 

siblings 98 

size 101-2 

states 119-20 

text strings 106-7 

types 103 

user defined 113-15 
user editing 122-23 
walking the tree 100-101 
object states 119-20 
CHECKED 120 
CROSSED 120 
DISABLED 120 
OUTLINED 120 
SELECTED 119 
SHADOWED 120 
object trees 9, 98 
ob_next 98 
ob_spec 104-5 
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ob-states 119 
ob_taiI 98 
ob_type 103 
opcode 11-12 
output parameter arrays 12 
overlap rectangle 62 
Parameter Block 15 
parameter shape 16 
PARMBLK 113-14 
pb—currstate 114 
pb_objc 114 
pb_parm 114 
pb_ prevstate 114 
pb_tree 114 
PEEK 14 

phys_handle( ) 23 
physical screen handle 23 
pointers 98, 188-89 
address 188 
shape 189 
points 60 
polling 53, 94 
programs 

aesshell.s 40-47 
deskacc.c 204-9 
deskacc.s 210-18 
dialogl.c 164-69 
dialog2.c 182-83 
dummy.c 35-39 
dummy. s 49-50 
fselect.bas 174-75 
fselect.c 172-73 
menul.c 144-48 
menu2.c 150-52 
message. c 69-72 
message.s 73-78 
mousform.c 190-92 
mousform.s 192-95 
object.c 125 
object.s 126-28 
scroll. c 84-87 

RAM (Random Access Memory), allo- 
cating 9-10 
raster coordinates 22 
Ready list 5 
rectangle list 58-60 

finding visible rectangles 58 
window refresh procedure 59 
rectangles 60, 101-2 

convert from AES to VDI 60 
finding overlapping 101-2 
redraw messages 63, 65-66 

sending to your own application 63 
resolution mode 22-23 
Resource Construction Set (RCS) 131 


resource files 9, 131-39 

converting position/size values to 
pixels 138 
loading 136-37 
store data structure addresses 
138-39 
structure 134 
Tree Index 135 

using construction programs 132-34 
Resource Library 8-9 
root object (object number 0) 98 
RSCBUILD.C program 152 
R_STRING 137 
RTARROW 78 
R—TREE 143 
rubber box 179 
Scrap Library 8 
SCREEN 141 

screen display, unlocking 61 
Screen Manager 6-7, 56 
scroll bars. See slide bars 
separator bar 142 
SETBLOCK 48, 201 
Shell Library 9 
short 17 

sibling objects 98 
sizer control 64 
slide bars 78-87 
slider 25, 78-83 

calculating position 81 
finding position 82 
position 80-83 

rounding slider movement 82 
size 79-80 
slider box 78 
snapping 68 
startup file 39 
static array 33 
status 22 
ST BASIC 14-16 

array starting addresses 14 
ASK MOUSE 15-16 
calls 14-16 
reading arrays 15 
writing arrays 15 
struct 98 
TAIL field 99 
TEDINFO 108-10 
timer events 91-92 
title bar 25 

TOS (Tramiel Operating System) 3 
TOUCHEXIT 118 

TPA (Transient Program Area) 47, 201 
Tramiel Operating System. See TOS 
Transient Program Area. See TPA 
UPARROW 78 
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USERBLK. See APPLBLK 
user-defined objects 113-15 
validation characters 109 
VDI (Virtual Device Interface) 4, 22, 60 
converting from AES 60 
opening a screen workstation 22 
Virtual Device Interface. See VDI 
visual hierarchy 101 
v_opnvwk( ) 22 
vs_clip( ) 60 
vs_color( ) 105-6 
VSLIDE 78 

walking the rectangle list 58 
WF_HSLIDE 83 
WF—VSLIDE 83 
wind_get0 29, 58 

valid flag values (table) 29 
Window library 8 

windows 23-35, 56-62, 64-68, 83-84, 
186-87 

aligning the left edge 68 
appearing completely on screen 67 
application 24 

calculating start position 83-84 
closing 34 

computing overlap area 59-60 
control features 24-25 
controlling the work area 65 
creating 26-31 

creating exploding windows 186-87 
exchanging exterior and interior size 
65 



finding dimensions 29-31 
finding exterior dimensions 34 
finding interior dimensions 33 
GEM Desktop 24 
handle 28-29 
maximum dimensions 27 
moving 67 
moving to the top 68 
opening 31-34 
paging through 25 
position 27-28 
possible attributes 26-27 
redrawing 65-66 
refreshing 56-62 
removing 35 
restoring contents 57 
sizing 27, 64-67 
updating the display 83 
WM—ARROWED 82-83 
WM—CLOSED 69 
WM— FULLED 66 
WM—HSLID 81 
WM-MOVED 67 
WM—REDRAW 56-57, 172 
WM-REFRESH 172 
WM—SIZED 64-67 
WM—TOPPED 68 
WM—VSLID 81-82 
XBIOS (extended Basic Input/Output 
System) 4-5 
zoom box 162 
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The Complete GEM AES Reference 

Intermediate to advanced Atari ST programmers will wel- 
come this exhaustive reference to the ST's friendly inter- 
face — the Application Environment Services. COMPUTERS 
Technical Reference Guide — Atari ST, Volume Two: The 
GEM AES gives you complete information on starting an 
application, a two-part explanation of the use of windows, 
and details about GEM graphics objects, resource files, 
and desk accessories, to name only a few of the topics 
covered. 

This is the second book in a series of three on the Atari 
ST. The first, concerned the Virtual Device Interface (VDI). 
COMPUTEI's Technical Reference Guide — Atari ST, Volume 
Two: The GEM AES takes you further into the underpinnings 
of the GEM interface. 

Here is a list of only a few of the ST features covered in 
this book: 

• Menus, alert boxes, and dialog boxes. 

• Input/output through radio buttons, mouse operation, 
and boxes. 

• Sample programs written in C, machine language, and 
BASIC. 

• Resource-development programs. 

• A complete AES (Application Environment Services) func- 
tion reference. 

• Full cross-referencing of functions by name and opcode. 

Sheldon Leemon has a long-standing reputation for 
accuracy, readability, and the assurance of expertise. In 
this book, he continues his investigation into the inner work- 
ings of one of the most versatile and popular computers 
on the market— -the Atari ST. 

COMPUTEI's Technical Reference Guide-Atari ST, Vol- 
ume Two: The GEM AES is the complete reference guide to 
the AES, the heart of the ST's friendly interface. 


$ 19.95 
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